@ic-reactor/vite-plugin 0.15.1 → 4.0.0-beta.2

package/src/index.ts

@@ -1,61 +1,77 @@
 /**
  * @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 fs from "node:fs"
+import path from "node:path"
 import type {
+  Logger,
   Plugin,
   ProxyOptions,
   ResolvedConfig,
   UserConfig,
   ViteDevServer,
 } from "vite"
-import fs from "node:fs"
-import path from "node:path"
-import {
-  findSharedOutDirs,
-  runCanisterPipeline,
-  sharedOutDirMessage,
-  type CanisterConfig,
-  type CodegenConfig,
-  type CodegenTarget,
-} from "@ic-reactor/codegen"
 import {
   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"
 
+/** 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. Set `factories: true` on an entry to
-   * also generate `index.factories.generated.ts`, a query or mutation object
-   * per method bound to the generated reactor; see `CanisterConfig.factories`.
-   */
-  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 }
+  >
   /**
    * 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
@@ -68,6 +84,8 @@ export interface IcReactorPluginOptions {
    * 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
@@ -75,49 +93,110 @@ 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"
 
+  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.
@@ -127,236 +206,304 @@ export function icReactor(options: IcReactorPluginOptions): Plugin {
   /** The options of the plugin's `/api` proxy, as Vite hands them over. */
   const apiProxyOptions = new Set<ProxyOptions>()
 
-  // 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.
+  // 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)
-    )
+  // ── Generation ──────────────────────────────────────────────────────────
+
+  const didPath = (canister: Generated) =>
+    path.resolve(projectRoot, canister.didFile)
+  const relativeToRoot = (file: string) =>
+    path.relative(projectRoot, file) || "."
+
   /**
-   * The `.did` text each entry last generated from, so a watch rebuild can
-   * tell which entries need regenerating. See `buildStart`.
+   * 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<CanisterConfig, string>()
+  const generatedFrom = new Map<string, string>()
+
+  /**
+   * 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 entry's `.did` text, or `undefined` when it cannot be read. */
-  const readDidSource = (canister: CanisterConfig): string | undefined => {
+  /** 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(resolveDidPath(canister.didFile), "utf-8")
+      return fs.readFileSync(didPath(canister), "utf-8")
     } catch {
       return undefined
     }
   }
 
-  /** How an error names an entry: its position, since names can repeat. */
-  const describeEntry = (canister: CanisterConfig) =>
-    `canisters[${canisters.indexOf(canister)}] (${JSON.stringify(canister.name)})`
-
   /**
-   * The CLI's error for an entry that generates into the directory of an
-   * earlier entry, or `undefined` when it has a directory of its own.
+   * 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.
    *
-   * The pipeline's owner marker records a name, so two entries with the same
-   * `name` and `outDir` both passed it. Both generated into one directory at
-   * once, and which one's output survived changed from run to run while the
-   * build succeeded. Every configured entry takes part, including ones this run
-   * does not regenerate. Called right before each entry's pipeline starts: an
-   * earlier entry's pipeline creates its directory before its first await, so
-   * a later entry reaching that directory through a symlink or a spelling that
-   * differs only in case is caught too, as the CLI catches it.
-   */
-  const sharedOutDirError = (canister: CanisterConfig): string | undefined => {
-    const first = findSharedOutDirs(
-      canisters.map((entry) => [entry, entry] as const),
-      outDir,
-      projectRoot
-    ).get(canister)
-    return first === undefined
-      ? undefined
-      : sharedOutDirMessage(describeEntry(canister), describeEntry(first))
-  }
-
-  const configuredCanisterIds = Object.fromEntries(
-    canisters
-      .filter((canister) => !!canister.canisterId)
-      .map((canister) => [canister.name, canister.canisterId as string])
-  )
-
-  /**
-   * Report a generation failure everywhere a developer might be looking.
+   * Resolves `undefined` when `signal` was aborted before it finished: the
+   * server it belonged to is gone, so nothing is recorded, logged or shown.
    *
-   * Terminal output scrolls away behind request logs and HMR chatter, so in dev
-   * the browser error overlay is the signal that actually gets noticed.
+   * @param force - Generate even a canister whose `.did` text is unchanged.
+   * @param signal - The `stopper` signal current when the run was asked for.
    */
-  /**
-   * The failures that are still unfixed, one per configured canister entry,
-   * kept so a browser that was not connected when one happened still gets the
-   * overlay.
-   *
-   * 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.
-   *
-   * 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.
-   *
-   * Keyed by the entry rather than by `name`, since two entries can share a
-   * name. See `inFlight`.
-   */
-  const pendingFailures = new Map<
-    CanisterConfig,
-    { 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,
-    }
-
-    server?.ws.send({ type: "error", err })
-    return { message: err.message, stack: err.stack }
-  }
+  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 []
 
-  // 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 writes a canister's
-  // declarations in one synchronous step, after all of them are generated,
-  // 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 it can settle before the newest `.did` has been written.
-  // The trailing run sends its own full-reload, so the browser still converges.
-  //
-  // Both maps are keyed by the configured entry, not by its `name`. Two entries
-  // can share a name, for one canister generated twice into different outDirs,
-  // say as a DisplayReactor and as a Reactor. Keyed by name, a save that touched
-  // both queued the second behind the first, and the trailing rerun then
-  // regenerated the first entry again. The second kept stale bindings.
-  const inFlight = new Map<CanisterConfig, Promise<void>>()
-  const rerunQueued = new Set<CanisterConfig>()
-
-  const regenerate = (
-    canisterConfig: CanisterConfig,
-    server: ViteDevServer
-  ): Promise<void> => {
-    const { name } = canisterConfig
-    const running = inFlight.get(canisterConfig)
-
-    if (running) {
-      rerunQueued.add(canisterConfig)
-      return running
-    }
+      let cli: string
+      try {
+        cli = resolveCliBin(projectRoot)
+      } catch (error) {
+        return stale.map((canister) => ({ canister, message: describe(error) }))
+      }
 
-    const sharedError = sharedOutDirError(canisterConfig)
-    if (sharedError !== undefined) {
-      pendingFailures.set(
-        canisterConfig,
-        reportFailure(server, `Regeneration failed for ${sharedError}`)
-      )
-      return Promise.resolve()
-    }
+      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) => {
-        reportWarnings(name, result.warnings)
-        if (result.success) {
-          // A later connection must not be handed a failure that has since been
-          // fixed.
-          pendingFailures.delete(canisterConfig)
-          // Reload page to reflect new types/hooks
-          server.ws.send({ type: "full-reload" })
-        } else {
-          pendingFailures.set(
-            canisterConfig,
-            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(
-          canisterConfig,
-          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(canisterConfig)
-        if (rerunQueued.delete(canisterConfig)) {
-          void regenerate(canisterConfig, server)
         }
-      })
-
-    inFlight.set(canisterConfig, run)
-    return run
+      }
+      return failures
+    } catch (error) {
+      if (signal.aborted) return undefined
+      return wanted.map((canister) => ({ canister, message: describe(error) }))
+    }
   }
 
   /**
-   * Regenerate every entry whose `.did` is `file`, and do nothing for any
-   * other file.
-   *
-   * Every entry, 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.
+   * The error text for failed canisters. Canisters that failed for the same
+   * reason (no CLI installed, one crash) are listed under it once.
    */
-  const regenerateForDid = (file: string, server: ViteDevServer): void => {
-    if (!file.endsWith(".did")) {
-      return
+  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])
     }
-
-    const changedPath = path.normalize(file)
-    const affectedCanisters = canisters.filter(
-      (canister) => resolveDidPath(canister.didFile) === changedPath
+    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")
     )
+  }
+
+  /**
+   * 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 (affectedCanisters.length === 0) {
+  /**
+   * 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)
+  }
 
-    console.log(
-      `[ic-reactor] .did file changed: ${affectedCanisters
-        .map((canister) => canister.name)
-        .join(", ")}. Regenerating...`
+  /**
+   * 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)
+    })
+  }
 
-    // `regenerate` reports its own failures and never rejects.
-    for (const canister of affectedCanisters) {
-      void regenerate(canister, server)
+  /**
+   * 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)}`)
+      }
+    })
+  }
+
+  /** 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)
     }
   }
 
@@ -364,10 +511,14 @@ export function icReactor(options: IcReactorPluginOptions): Plugin {
     name: PLUGIN_NAME,
     enforce: "pre", // Run before other plugins
 
-    async config(userConfig, { command: viteCommand }) {
+    async config(userConfig, { command: viteCommand, mode }) {
+      announceGuide(userConfig)
       command = viteCommand
 
-      if (viteCommand !== "serve" || !injectEnvironment) {
+      // 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 {}
       }
 
@@ -377,9 +528,7 @@ export function icReactor(options: IcReactorPluginOptions): Plugin {
       const ownsApiProxy = !userConfig.server?.proxy?.["/api"]
 
       const environment = createLocalEnvironment({
-        canisterNames: canisters
-          .map((canister) => canister.name)
-          .filter((name): name is string => !!name),
+        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
@@ -399,7 +548,7 @@ export function icReactor(options: IcReactorPluginOptions): Plugin {
       localEnvironment = environment
 
       const state = await environment.detect()
-      warnAboutIncompleteDetection(state, canisters.length > 0, ownsApiProxy)
+      warnAboutIncompleteDetection(state, names.length > 0, ownsApiProxy)
 
       return {
         server: {
@@ -428,11 +577,12 @@ export function icReactor(options: IcReactorPluginOptions): Plugin {
     },
 
     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) {
@@ -444,40 +594,24 @@ export function icReactor(options: IcReactorPluginOptions): Plugin {
         server.middlewares.use(icEnvMiddleware(localEnvironment))
       }
 
-      // 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, since they are not in the module graph.
-      const didFiles = canisters.map((c) => resolveDidPath(c.didFile))
-      server.watcher.add(didFiles)
-
-      // Regenerate from the watcher's own events, not from `handleHotUpdate`.
-      // Vite calls that hook only for a file changed in place, and only while
-      // HMR is on. A .did created after startup, or deleted and written again
-      // by a build tool or `git checkout`, arrives as an `add` event, which is
-      // all Vite 4 to 7 report for it, so its bindings stayed missing or stale.
-      // With `server.hmr: false`, no save regenerated at all.
-      const onDidEvent = (file: string) => regenerateForDid(file, server)
-      server.watcher.on("change", onDidEvent)
-      server.watcher.on("add", onDidEvent)
+      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)
     },
 
     // `vite preview` resolves the config with the `serve` command too, and
@@ -489,147 +623,39 @@ export function icReactor(options: IcReactorPluginOptions): Plugin {
     },
 
     async buildStart() {
-      // ── Code Generation ──────────────────────────────────────────────────
+      if (generated.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 canisters) {
-        if (typeof canister.didFile === "string") {
-          this.addWatchFile(resolveDidPath(canister.didFile))
-        }
-      }
+      for (const canister of generated) this.addWatchFile(didPath(canister))
 
-      // A watch rebuild calls buildStart again, whatever file started it. A
-      // run used to rewrite the generated files even when their content was
-      // the same, those files are in the module graph, and the watcher then
-      // started another rebuild, which regenerated again: one edit to any
-      // source file looped forever. Codegen now leaves an unchanged file alone,
-      // and a rebuild still regenerates only the entries whose `.did` changed
-      // since they last generated, which skips parsing and formatting the
-      // rest. A failed entry is retried.
-      const sources = canisters.map(readDidSource)
-      const pending = canisters.filter(
-        (canister, index) =>
-          !this.meta.watchMode ||
-          sources[index] === undefined ||
-          generatedFrom.get(canister) !== sources[index]
+      const { signal } = stopper
+      const failures = await serially(() =>
+        generateNow(generated, false, signal)
       )
-
-      if (pending.length === 0) {
-        return
+      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)
+    },
 
-      console.log(
-        `[ic-reactor] Generating canister bindings for ${pending.length} canisters...`
-      )
-
-      // Each entry is checked just before its pipeline starts, so the check
-      // sees the directories the entries before it have claimed.
-      const outcomes = await Promise.allSettled(
-        pending.map((canisterConfig) => {
-          const sharedError = sharedOutDirError(canisterConfig)
-          if (sharedError !== undefined) {
-            return Promise.reject(new SharedOutDirError(sharedError))
-          }
-          return runCanisterPipeline({
-            canisterConfig,
-            projectRoot,
-            globalConfig,
-          })
-        })
-      )
-
-      outcomes.forEach((outcome, index) => {
-        const canister = pending[index]
-        const source = sources[canisters.indexOf(canister)]
-        if (outcome.status === "fulfilled") {
-          reportWarnings(canister.name, outcome.value.warnings)
-        }
-        if (
-          outcome.status === "fulfilled" &&
-          outcome.value.success &&
-          source !== undefined
-        ) {
-          generatedFrom.set(canister, source)
-        } else {
-          generatedFrom.delete(canister)
-        }
-      })
-
-      // 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 canister = pending[index]
-        const name = canister?.name ?? `canister #${index}`
-
-        if (outcome.status === "rejected") {
-          // The shared-outDir error names the entry itself.
-          const detail =
-            outcome.reason instanceof SharedOutDirError
-              ? outcome.reason.message
-              : `${name}: ${describeError(outcome.reason)}`
-          return [{ canister, detail }]
-        }
-        if (!outcome.value.success) {
-          return [
-            {
-              canister,
-              detail: `${name}: ${outcome.value.error ?? "unknown error"}`,
-            },
-          ]
-        }
-        return []
-      })
-
-      if (failures.length === 0) {
-        return
-      }
-
-      const message =
-        `Failed to generate ${failures.length} of ${pending.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}`)
-      }
-
-      reportFailure(devServer, message)
-
-      // One entry per canister, so fixing one of them removes only its own line
-      // from the replay.
-      for (const { canister, detail } of failures) {
-        pendingFailures.set(canister, {
-          message: `[ic-reactor] Failed to generate ${detail}`,
-          stack: "",
-        })
-      }
+    // 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
 }
 
-/** An entry refused because an earlier entry generates into its directory. */
-class SharedOutDirError extends Error {}
-
-/**
- * Print what a canister's generation could not fix itself, such as an
- * `index.ts` of the user's own that does not re-export the factories it
- * generated. A warning never fails the run.
- */
-function reportWarnings(name: string, warnings: string[] | undefined): void {
-  for (const warning of warnings ?? []) {
-    console.warn(`[ic-reactor] ${name}: ${warning}`)
-  }
-}
-
-/** 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)
 }