@softarc/native-federation 4.3.1 → 4.4.0

package/dist/lib/core/build/shared-bundle-plan.js

@@ -0,0 +1,70 @@
+import { inferPackageFromSecondary, normalizePackageName } from "../../utils/normalize.js";
+function splitShared(shared) {
+  const sharedServer = {};
+  const sharedBrowser = {};
+  const separateBrowser = {};
+  const separateServer = {};
+  for (const key in shared) {
+    const obj = shared[key];
+    if (obj?.platform === "node") {
+      if (obj.build === "default") sharedServer[key] = obj;
+      else separateServer[key] = obj;
+    } else if (obj?.platform === "browser") {
+      if (obj.build === "default") sharedBrowser[key] = obj;
+      else separateBrowser[key] = obj;
+    }
+  }
+  return { sharedBrowser, sharedServer, separateBrowser, separateServer };
+}
+function planSeparate(separate, platform, externals) {
+  const grouped = {};
+  for (const [key, shared] of Object.entries(separate)) {
+    const packageName = shared.build === "separate" ? key : inferPackageFromSecondary(key);
+    if (!grouped[packageName]) grouped[packageName] = { chunks: shared.chunks, entries: {} };
+    grouped[packageName].entries[key] = shared;
+  }
+  return Object.entries(grouped).map(([packageName, group]) => ({
+    bundleName: `${platform}-${normalizePackageName(packageName)}`,
+    platform,
+    chunks: group.chunks,
+    entries: group.entries,
+    externals: externals.filter((e) => !e.startsWith(packageName)),
+    keys: Object.keys(group.entries),
+    kind: "separate"
+  }));
+}
+function planSharedBundles(config, externals) {
+  const { sharedBrowser, sharedServer, separateBrowser, separateServer } = splitShared(
+    config.shared
+  );
+  const plans = [];
+  if (Object.keys(sharedBrowser).length > 0) {
+    plans.push({
+      bundleName: "browser-shared",
+      platform: "browser",
+      chunks: config.chunks,
+      entries: sharedBrowser,
+      externals,
+      keys: Object.keys(sharedBrowser),
+      kind: "shared"
+    });
+  }
+  if (Object.keys(sharedServer).length > 0) {
+    plans.push({
+      bundleName: "node-shared",
+      platform: "node",
+      chunks: config.chunks,
+      entries: sharedServer,
+      externals,
+      keys: Object.keys(sharedServer),
+      kind: "shared"
+    });
+  }
+  plans.push(...planSeparate(separateBrowser, "browser", externals));
+  plans.push(...planSeparate(separateServer, "node", externals));
+  return plans;
+}
+export {
+  planSharedBundles,
+  splitShared
+};

package/dist/lib/core/build/synthesize-cjs-exports.d.ts

@@ -0,0 +1,12 @@
+import type { IoPort } from '../../domain/utils/io-port.contract.js';
+import type { PackageInfo } from '../../domain/utils/package-json.contract.js';
+/** Evaluates a module at build time (Node `require`) and returns its value, or throws. */
+export type ModuleEvaluator = (absPath: string) => unknown;
+/**
+ * For a CommonJS shared external, `require()`s it, enumerates its runtime named
+ * exports, and writes a synthetic ESM entry re-exporting them.
+ *
+ * Returns the synthetic entry path, or `null` to keep the original entry (not a CJS
+ * candidate, no names to wrap, or a `require()` failure → default-only fallback).
+ */
+export declare function synthesizeCjsNamedExportsEntry(io: IoPort, evaluateModule: ModuleEvaluator, pi: PackageInfo, cachePath: string, outName: string): string | null;

package/dist/lib/core/build/synthesize-cjs-exports.js

@@ -0,0 +1,58 @@
+import * as path from "path";
+import { logger } from "../../utils/logger.js";
+import { isCjsCandidate } from "../../utils/package/esm-detection.js";
+import {
+  planCjsWrap,
+  buildSyntheticCjsEntry,
+  isEsmInteropError
+} from "../../utils/package/cjs-named-exports.js";
+const SYNTHETIC_DIR = ".nf-cjs-entries";
+const warned = /* @__PURE__ */ new Set();
+function nearestPackageType(io, fromDir) {
+  let dir = fromDir;
+  for (; ; ) {
+    const pkg = path.join(dir, "package.json");
+    if (io.exists(pkg)) {
+      try {
+        const type = JSON.parse(io.readText(pkg))?.type;
+        return type === "module" || type === "commonjs" ? type : void 0;
+      } catch {
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function synthesizeCjsNamedExportsEntry(io, evaluateModule, pi, cachePath, outName) {
+  const entryPoint = pi.entryPoint;
+  const candidate = isCjsCandidate({
+    esm: pi.esm,
+    entryPoint,
+    packageType: nearestPackageType(io, path.dirname(entryPoint)),
+    readSource: () => io.readText(entryPoint)
+  });
+  if (!candidate) return null;
+  let plan;
+  try {
+    plan = planCjsWrap(evaluateModule(entryPoint));
+  } catch (err) {
+    if (!isEsmInteropError(err) && !warned.has(entryPoint)) {
+      warned.add(entryPoint);
+      const detail = err instanceof Error ? err.message : String(err);
+      logger.warn(
+        `[native-federation] Could not enumerate named exports of "${entryPoint}" at build time (${detail}); falling back to default-only. Named imports from this package may fail across the module boundary.`
+      );
+    }
+    return null;
+  }
+  if (!plan.wrap) return null;
+  const dir = path.join(cachePath, SYNTHETIC_DIR);
+  io.mkdirp(dir);
+  const syntheticPath = path.join(dir, outName);
+  io.writeText(syntheticPath, buildSyntheticCjsEntry(entryPoint, plan.keys));
+  return syntheticPath;
+}
+export {
+  synthesizeCjsNamedExportsEntry
+};

package/dist/lib/core/cache/cache-persistence.d.ts

@@ -1,10 +1,12 @@
 import type { NormalizedExternalConfig } from '../../domain/config/external-config.contract.js';
+import type { NormalizedFederationConfig } from '../../domain/config/federation-config.contract.js';
 import type { ChunkInfo, IntegrityMap, SharedInfo } from '../../domain/core/federation-info.contract.js';
 import type { FileReaderPort, FileWriterPort, HashPort } from '../../domain/utils/io-port.contract.js';
 export declare const getDefaultCachePath: (workspaceRoot: string) => string;
 export declare const getFilename: (title: string, dev?: boolean) => string;
-export declare const getChecksum: (shared: Record<string, NormalizedExternalConfig>, dev: "1" | "0", builderVersion?: string) => string;
-export declare const getChecksumCore: (hash: HashPort, shared: Record<string, NormalizedExternalConfig>, dev: "1" | "0", builderVersion?: string) => string;
+export declare const getChecksum: (shared: Record<string, NormalizedExternalConfig>, dev: "1" | "0", builderVersion?: string, features?: FeatureFlags, contentSignals?: Record<string, string>, resolvedVersions?: Record<string, string>) => string;
+export type FeatureFlags = Partial<NormalizedFederationConfig['features']>;
+export declare const getChecksumCore: (hash: HashPort, shared: Record<string, NormalizedExternalConfig>, dev: "1" | "0", builderVersion?: string, features?: FeatureFlags, contentSignals?: Record<string, string>, resolvedVersions?: Record<string, string>) => string;
 export type CacheMetadata = {
     checksum: string;
     externals: SharedInfo[];

package/dist/lib/core/cache/cache-persistence.js

@@ -6,12 +6,31 @@ const getFilename = (title, dev) => {
   const devSuffix = dev ? "-dev" : "";
   return `${title}${devSuffix}.meta.json`;
 };
-const getChecksum = (shared, dev, builderVersion = "") => getChecksumCore(nodeIo, shared, dev, builderVersion);
-const getChecksumCore = (hash, shared, dev, builderVersion = "") => {
+const getChecksum = (shared, dev, builderVersion = "", features = {}, contentSignals = {}, resolvedVersions = {}) => getChecksumCore(nodeIo, shared, dev, builderVersion, features, contentSignals, resolvedVersions);
+const featureState = (features) => Object.entries(features).sort(([a], [b]) => a < b ? -1 : 1).map(([flag, on]) => `${flag}=${on ? "1" : "0"}`).join(",");
+const SHARED_INFO_FIELDS = [
+  "requiredVersion",
+  "singleton",
+  "strictVersion",
+  "shareScope",
+  "pool"
+];
+const sharedInfoState = (config) => {
+  const values = SHARED_INFO_FIELDS.map((field) => config[field] ?? null);
+  return values.every((value) => value === null) ? "" : `!${JSON.stringify(values)}`;
+};
+const getChecksumCore = (hash, shared, dev, builderVersion = "", features = {}, contentSignals = {}, resolvedVersions = {}) => {
   const denseExternals = Object.keys(shared).sort().reduce((clean, external) => {
-    return clean + ":" + external + (shared[external].version ? `@${shared[external].version}` : "");
+    const installed = resolvedVersions[external];
+    const declared = shared[external].version;
+    const version = installed ? `~${installed}` : declared ? `@${declared}` : "";
+    const signal = contentSignals[external] ? `#${contentSignals[external]}` : "";
+    return clean + ":" + external + version + sharedInfoState(shared[external]) + signal;
   }, "deps");
-  return hash.hash("sha256", denseExternals + `:dev=${dev}:builder=${builderVersion}`).hex();
+  return hash.hash(
+    "sha256",
+    denseExternals + `:dev=${dev}:builder=${builderVersion}:features=${featureState(features)}`
+  ).hex();
 };
 const cacheEntryCore = (io, pathToCache, fileName) => {
   const metadataFile = path.join(pathToCache, fileName);
@@ -33,8 +52,11 @@ const cacheEntryCore = (io, pathToCache, fileName) => {
       io.mkdirp(fullOutputPath);
       cachedResult.files.forEach((file) => {
         const cachedFile = path.join(pathToCache, file);
-        const distFileName = path.join(fullOutputPath, file);
-        if (io.exists(cachedFile)) io.copyFile(cachedFile, distFileName);
+        if (!io.exists(cachedFile))
+          throw new Error(
+            `Cached artifact '${file}' recorded in '${metadataFile}' is missing. Delete '${pathToCache}' and rebuild.`
+          );
+        io.copyFile(cachedFile, path.join(fullOutputPath, file));
       });
     },
     clear: () => {

package/dist/lib/core/federation-builder.d.ts

@@ -1,6 +1,6 @@
 import type { FederationInfo } from '../domain/core/federation-info.contract.js';
 import type { NormalizedFederationConfig } from '../domain/config/federation-config.contract.js';
-import { type FederationOptions } from '../domain/core/federation-options.contract.js';
+import { type FederationOptions, type NormalizedFederationOptions } from '../domain/core/federation-options.contract.js';
 import type { NFBuildAdapter } from '../domain/core/build-adapter.contract.js';
 export interface BuildHelperParams {
     options: FederationOptions;
@@ -19,5 +19,6 @@ export declare const federationBuilder: {
     readonly federationInfo: FederationInfo;
     readonly externals: string[];
     readonly config: NormalizedFederationConfig;
+    readonly options: NormalizedFederationOptions;
 };
 export {};

package/dist/lib/core/federation-builder.js

@@ -46,6 +46,9 @@ const federationBuilder = {
   },
   get config() {
     return config;
+  },
+  get options() {
+    return options;
   }
 };
 export {

package/dist/lib/core/normalize-options.d.ts

@@ -1,11 +1,11 @@
 import type { NormalizedFederationConfig } from '../domain/config/federation-config.contract.js';
 import type { FederationOptions, NormalizedFederationOptions } from '../domain/core/federation-options.contract.js';
-import type { FileReaderPort } from '../domain/utils/io-port.contract.js';
+import type { FileReaderPort, GlobPort } from '../domain/utils/io-port.contract.js';
 import { type FederationCache } from '../../domain.js';
 import { getUsedDependenciesFactory } from '../config/get-used-dependencies.js';
 type ConfigLoader = (fullConfigPath: string) => Promise<NormalizedFederationConfig>;
 interface NormalizeFederationDeps {
-    io: FileReaderPort;
+    io: FileReaderPort & GlobPort;
     loadConfig: ConfigLoader;
     usedDependenciesFactory?: typeof getUsedDependenciesFactory;
 }

package/dist/lib/core/normalize-options.js

@@ -2,6 +2,8 @@ import * as path from "path";
 import { pathToFileURL } from "url";
 import { nodeIo } from "../utils/io/node-io-adapter.js";
 import { removeUnusedDeps } from "../config/remove-unused-deps.js";
+import { expandOrDropWildcards } from "../config/expand-mappings.js";
+import { assertBarrelMappings } from "../config/validate-mappings.js";
 import { createFederationCache } from "./cache/federation-cache.js";
 import { getDefaultCachePath } from "./cache/cache-persistence.js";
 import { getUsedDependenciesFactory } from "../config/get-used-dependencies.js";
@@ -31,25 +33,29 @@ async function normalizeFederationOptionsCore(deps, options, cache) {
     cacheExternalArtifacts: options.cacheExternalArtifacts ?? true,
     federationCache
   };
-  if (config.features.ignoreUnusedDeps) {
+  const nothingShared = Object.keys(config.shared).length === 0 && Object.keys(config.sharedMappings).length === 0;
+  if (nothingShared) {
+    logger.debug("Nothing is shared, skipping the used dependency scan.");
+  } else if (config.features.ignoreUnusedDeps) {
     const getUsedDeps = (deps.usedDependenciesFactory ?? getUsedDependenciesFactory)(
       options.workspaceRoot,
       options.entryPoints
     );
-    config = removeUnusedDeps(getUsedDeps(config), config);
+    config = removeUnusedDeps(getUsedDeps(config), config, {
+      io: deps.io,
+      workspaceRoot: options.workspaceRoot
+    });
     logger.info("Removed unused dependencies.");
     logger.debug(
       'This can be disabled per dependency/external using the "includeSecondaries: {keepAll: true}" property. Or in general by disabling the "ignoreUnusedDeps" feature. '
     );
   } else {
-    const withWildcard = Object.keys(config.sharedMappings).some((m) => m.includes("*"));
-    if (withWildcard) {
-      logger.warn(
-        "Sharing mapped paths with wildcards (*) is only supported with ignoreUnusedDeps feature."
-      );
-      config.sharedMappings = Object.entries(config.sharedMappings).filter(([_path]) => !_path.includes("*")).reduce((acc, [_path, _import]) => ({ ...acc, [_path]: _import }), {});
-    }
+    config.sharedMappings = expandOrDropWildcards(config, {
+      io: deps.io,
+      workspaceRoot: options.workspaceRoot
+    });
   }
+  assertBarrelMappings(config.sharedMappings);
   return { config, options: normalizedOptions };
 }
 function resolveProjectName(name) {

package/dist/lib/core/output/densify-externals.js

@@ -40,6 +40,7 @@ function densifyExternals(shared) {
       if (entry.version !== void 0) dense.version = entry.version;
       if (entry.shareScope !== void 0) dense.shareScope = entry.shareScope;
       if (entry.bundle !== void 0) dense.bundle = entry.bundle;
+      if (entry.pool !== void 0) dense.pool = entry.pool;
       if (entry.dev !== void 0) dense.dev = entry.dev;
       groupIndex.set(key, result.length);
       result.push(dense);

package/dist/lib/domain/config/federation-config.contract.d.ts

@@ -1,16 +1,40 @@
 import type { PreparedSkipList, SkipList } from './skip-list.contract.js';
 import type { PathToImport } from '../utils/mapped-path.contract.js';
-import type { NormalizedSharedExternalsConfig, SharedExternalsConfig } from './external-config.contract.js';
+import type { ExternalConfig, NormalizedSharedExternalsConfig, SharedExternalsConfig } from './external-config.contract.js';
 export type ExposeEntry = {
     file: string;
     element?: string;
 };
+export type SharedMappingEntry = string | [string[], ExternalConfig];
+/** Selection pattern -> config, kept in declaration order: first match wins. */
+export type SharedMappingConfigs = Record<string, ExternalConfig>;
+/**
+ * Only the subset of `ExternalConfig` a mapping can act on — mappings all share the
+ * single `mapping-or-exposed` bundle, so `build`/`platform`/`chunks`/`packageInfo`
+ * have nothing to select. `requiredVersion` and `version` stay optional because their
+ * defaults are read from the mapped lib's package.json at build time.
+ *
+ * `includeSecondaries` collapses to a boolean exactly as it does for a shared external:
+ * it means "exempt from `ignoreUnusedDeps` pruning". `resolveGlob` is lifted out of it
+ * because a mapping has no secondary entry points for it to apply to.
+ */
+export interface NormalizedMappingConfig {
+    singleton: boolean;
+    strictVersion: boolean;
+    requiredVersion?: string;
+    version?: string;
+    shareScope?: string;
+    pool?: string;
+    includeSecondaries?: boolean;
+    resolveGlob?: boolean;
+}
+export type NormalizedSharedMappingConfigs = Record<string, NormalizedMappingConfig>;
 export interface FederationConfig {
     name?: string;
     exposes?: Record<string, string | ExposeEntry>;
     shared?: SharedExternalsConfig;
     platform?: 'browser' | 'node';
-    sharedMappings?: Array<string>;
+    sharedMappings?: Array<SharedMappingEntry>;
     chunks?: boolean;
     skip?: SkipList;
     externals?: string[];
@@ -21,6 +45,7 @@ export interface FederationConfig {
         denseChunking?: boolean;
         denseExternals?: boolean;
         integrityHashes?: boolean;
+        synthesizeCjsExports?: boolean;
     };
 }
 export interface NormalizedFederationConfig {
@@ -29,6 +54,7 @@ export interface NormalizedFederationConfig {
     exposes: Record<string, ExposeEntry>;
     shared: NormalizedSharedExternalsConfig;
     sharedMappings: PathToImport;
+    sharedMappingsConfig: NormalizedSharedMappingConfigs;
     skip: PreparedSkipList;
     chunks: boolean;
     externals: string[];
@@ -39,5 +65,6 @@ export interface NormalizedFederationConfig {
         denseChunking: boolean;
         denseExternals: boolean;
         integrityHashes: boolean;
+        synthesizeCjsExports: boolean;
     };
 }

package/dist/lib/domain/utils/file-watcher.contract.d.ts

@@ -1,10 +1,28 @@
 export interface NfFileWatcherOptions {
     onChange?: (path: string) => void;
+    pollIntervalMs?: number;
+    debounceMs?: number;
+    /** Drop events whose mtime is unchanged since the last one seen for that path.
+     *  macOS FSEvents re-delivers 'changed' for recently edited files roughly every
+     *  30s; with a watch list of a few thousand sources that replay alone keeps a
+     *  rebuild loop awake forever. Default: true. */
+    dedupeReplays?: boolean;
+    /** Grace period after a path's recorded mtime during which an event whose mtime
+     *  and byte length both match still passes, covering a second save inside one
+     *  mtime tick. The 2000 default is twice the coarsest mtime granularity in play
+     *  (1s on gRPC-FUSE/NFS/WSL2 drvfs/HFS+); raise it for a filesystem coarser than
+     *  that, or for a network mount whose server clock runs behind the client.
+     *  See AGENTS.md "Replay dedupe". Default: 2000. */
+    replayGraceMs?: number;
+}
+interface AddPathsOptions {
+    poll?: boolean;
 }
 export interface NfFileWatcher {
-    addPaths(paths: string | readonly string[]): void;
+    addPaths(paths: string | readonly string[], opts?: AddPathsOptions): void;
     close(): Promise<void>;
     get(): ReadonlySet<string>;
     clear(): void;
     mutate(fn: (dirtyPaths: Set<string>) => void): void;
 }
+export {};

package/dist/lib/domain/utils/io-port.contract.d.ts

@@ -3,6 +3,12 @@ export interface Digest {
     hex(): string;
     base64(): string;
 }
+export interface StatInfo {
+    mtimeMs: number;
+    /** Byte length; 0 for directories. */
+    size: number;
+    isSymbolicLink: boolean;
+}
 export interface FileReaderPort {
     readText(path: string): string;
     readBytes(path: string): Uint8Array;
@@ -13,6 +19,8 @@ export interface FileReaderPort {
     isDirectory(path: string): boolean;
     /** Immediate child entry names (not full paths). Empty array on ENOENT, never throws. */
     readDir(path: string): string[];
+    realpath(path: string): string;
+    stat(path: string): StatInfo | null;
 }
 export interface FileWriterPort {
     writeText(path: string, data: string): void;
@@ -23,6 +31,7 @@ export interface FileWriterPort {
 export interface GlobPort {
     globFiles(pattern: string, opts: {
         cwd: string;
+        ignore?: string[];
     }): string[];
 }
 export interface HashPort {
@@ -31,15 +40,20 @@ export interface HashPort {
 export interface WatchHandle {
     close(): void;
 }
+interface WatchOptions {
+    recursive: boolean;
+    poll?: {
+        intervalMs: number;
+    };
+}
 export interface WatchPort {
     /**
-     * For a recursive directory watch `onEvent` receives the changed entry's
-     * filename relative to `path`; for a file it receives the path itself (or
-     * null when the platform omits it).
+     * `onEvent` receives the changed entry's filename relative to `path` (null when
+     * the platform omits it). Watching a file reports that file's own basename, so a
+     * caller that registered a file can ignore the argument.
      */
-    watch(path: string, opts: {
-        recursive: boolean;
-    }, onEvent: (filename: string | null) => void): WatchHandle;
+    watch(path: string, opts: WatchOptions, onEvent: (filename: string | null) => void): WatchHandle;
 }
 export interface IoPort extends FileReaderPort, FileWriterPort, GlobPort, HashPort, WatchPort {
 }
+export {};

package/dist/lib/utils/file-watcher.d.ts

@@ -1,7 +1,18 @@
 import type { WatchPort, FileReaderPort } from '../domain/utils/io-port.contract.js';
 import type { NfFileWatcher, NfFileWatcherOptions } from '../domain/utils/file-watcher.contract.js';
 export declare function createNfWatcher(options?: NfFileWatcherOptions): NfFileWatcher;
-export declare function createNfWatcherCore(io: WatchPort & FileReaderPort, options?: NfFileWatcherOptions): NfFileWatcher;
-export declare function syncNfFileWatcher(watcher: NfFileWatcher, bundlerCache: {
-    keys(): IterableIterator<string>;
-}): void;
+export declare function createNfWatcherCore(io: WatchPort & FileReaderPort, options?: NfFileWatcherOptions, now?: () => number): NfFileWatcher;
+/** A bundler cache keyed by input path, or the input paths themselves. */
+export type WatchSources = Iterable<string> | {
+    keys(): Iterable<string>;
+};
+/**
+ * Subscribe the watcher to the inputs the last build compiled.
+ *
+ * Passing a bundler cache only works when it is keyed by input path. A cache that
+ * records its inputs elsewhere yields an empty watch set and, silently, a dev server
+ * that serves stale bundles until restart — Angular's `SourceFileCache` extends `Map`
+ * but keeps its inputs in `typeScriptFileCache`/`referencedFiles`, which is
+ * angular-adapter#94. Adapters over such a cache must expand it and pass the paths.
+ */
+export declare function syncNfFileWatcher(watcher: NfFileWatcher, sources: WatchSources, linkedDirs?: readonly string[]): void;

package/dist/lib/utils/file-watcher.js

@@ -1,31 +1,130 @@
-import { join } from "path";
+import { dirname, join } from "path";
 import { nodeIo } from "./io/node-io-adapter.js";
 import { logger } from "./logger.js";
-import { toPosix } from "./path-patterns.js";
+import { isUnderDir, toPosix } from "./path-patterns.js";
 function createNfWatcher(options = {}) {
   return createNfWatcherCore(nodeIo, options);
 }
-function createNfWatcherCore(io, options = {}) {
+function createNfWatcherCore(io, options = {}, now = Date.now) {
   const { onChange } = options;
+  const pollIntervalMs = options.pollIntervalMs ?? 300;
+  const debounceMs = options.debounceMs ?? 0;
+  const dedupeReplays = options.dedupeReplays ?? true;
+  const replayGraceMs = options.replayGraceMs ?? 2e3;
   const watchers = /* @__PURE__ */ new Map();
   const dirtyPaths = /* @__PURE__ */ new Set();
-  const notify = (path) => {
+  const lastSeen = /* @__PURE__ */ new Map();
+  const trackedFiles = /* @__PURE__ */ new Set();
+  const fileDirWatchers = /* @__PURE__ */ new Map();
+  const dirKey = (p) => {
+    const posix = toPosix(p);
+    return posix.length > 1 ? posix.replace(/\/+$/, "") : posix;
+  };
+  const covers = (path, poll) => {
+    for (const [dir, watch] of watchers) {
+      if ((watch.poll || !poll) && isUnderDir(path, dir)) return true;
+    }
+    return false;
+  };
+  const supersede = (dir, poll) => {
+    for (const map of [watchers, fileDirWatchers]) {
+      for (const [key, watch] of map) {
+        if (watch.poll && !poll) continue;
+        if (map === watchers && key === dir) continue;
+        if (!isUnderDir(key, dir)) continue;
+        watch.handle.close();
+        map.delete(key);
+      }
+    }
+  };
+  const identityOf = (path) => {
+    let stat = io.stat(path);
+    if (stat?.isSymbolicLink) stat = io.stat(io.realpath(path));
+    return stat ? { mtimeMs: stat.mtimeMs, size: stat.size } : null;
+  };
+  const isReplay = (path, at) => {
+    const current = identityOf(path);
+    if (!current) {
+      lastSeen.delete(path);
+      return false;
+    }
+    const previous = lastSeen.get(path);
+    lastSeen.set(path, current);
+    if (!previous || previous.mtimeMs !== current.mtimeMs || previous.size !== current.size) {
+      return false;
+    }
+    return at - current.mtimeMs >= replayGraceMs;
+  };
+  let watchFailures = 0;
+  const watchFailed = (path) => {
+    if (++watchFailures > 1) return logger.debug(`Could not watch path '${path}'.`);
+    logger.warn(
+      `Could not watch '${path}'. Changes there will not trigger a rebuild; run with verbose logging to see any further watch failures.`
+    );
+  };
+  const deliver = (path, at) => {
+    if (dedupeReplays && isReplay(path, at)) return;
+    dirtyPaths.add(path);
     if (onChange) onChange(path);
-    else dirtyPaths.add(path);
+  };
+  const pending = /* @__PURE__ */ new Map();
+  let flushTimer;
+  const flush = () => {
+    for (const [p, at] of pending) deliver(p, at);
+    pending.clear();
+  };
+  const notify = (path) => {
+    const at = now();
+    if (debounceMs <= 0) return deliver(path, at);
+    if (!pending.has(path)) pending.set(path, at);
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(flush, debounceMs);
+    flushTimer.unref?.();
   };
   return {
-    addPaths(paths) {
+    addPaths(paths, opts) {
       const list = typeof paths === "string" ? [paths] : [...paths];
+      const shouldPoll = !!opts?.poll;
+      const poll = shouldPoll ? { intervalMs: pollIntervalMs } : void 0;
       for (const p of list) {
-        if (watchers.has(p)) continue;
+        if (io.isDirectory(p)) {
+          const dir2 = dirKey(p);
+          if (watchers.has(dir2) || covers(dir2, shouldPoll)) continue;
+          try {
+            watchers.set(dir2, {
+              handle: io.watch(p, { recursive: true, poll }, (filename) => {
+                if (filename) notify(toPosix(join(p, filename)));
+              }),
+              poll: shouldPoll
+            });
+          } catch {
+            watchFailed(p);
+            continue;
+          }
+          supersede(dir2, shouldPoll);
+          continue;
+        }
+        const key = toPosix(p);
+        if (trackedFiles.has(key)) continue;
+        trackedFiles.add(key);
+        if (dedupeReplays && !lastSeen.has(key)) {
+          const identity = identityOf(key);
+          if (identity) lastSeen.set(key, identity);
+        }
+        if (covers(key, shouldPoll)) continue;
+        const dir = dirKey(dirname(p));
+        if (fileDirWatchers.has(dir)) continue;
         try {
-          const isDir = io.isDirectory(p);
-          const handle = isDir ? io.watch(p, { recursive: true }, (filename) => {
-            if (filename) notify(toPosix(join(p, filename)));
-          }) : io.watch(p, { recursive: false }, () => notify(toPosix(p)));
-          watchers.set(p, handle);
+          fileDirWatchers.set(dir, {
+            handle: io.watch(dir, { recursive: false, poll }, (filename) => {
+              if (!filename) return;
+              const changed = toPosix(join(dir, filename));
+              if (trackedFiles.has(changed)) notify(changed);
+            }),
+            poll: shouldPoll
+          });
         } catch {
-          logger.debug(`Could not watch path '${p}'.`);
+          watchFailed(dir);
         }
       }
     },
@@ -33,16 +132,27 @@ function createNfWatcherCore(io, options = {}) {
     clear: () => dirtyPaths.clear(),
     mutate: (fn) => fn(dirtyPaths),
     async close() {
-      for (const handle of watchers.values()) {
+      if (flushTimer) clearTimeout(flushTimer);
+      for (const { handle } of [...watchers.values(), ...fileDirWatchers.values()]) {
         handle.close();
       }
       watchers.clear();
+      fileDirWatchers.clear();
+      trackedFiles.clear();
+      lastSeen.clear();
+      watchFailures = 0;
     }
   };
 }
-function syncNfFileWatcher(watcher, bundlerCache) {
-  const files = [...bundlerCache.keys()].filter((k) => !k.includes("node_modules"));
+function toPaths(sources) {
+  if (Array.isArray(sources)) return sources;
+  const cache = sources;
+  return typeof cache.keys === "function" ? cache.keys() : sources;
+}
+function syncNfFileWatcher(watcher, sources, linkedDirs = []) {
+  const files = [...toPaths(sources)].filter((k) => !k.includes("node_modules"));
   if (files.length) watcher.addPaths(files);
+  if (linkedDirs.length) watcher.addPaths(linkedDirs, { poll: true });
 }
 export {
   createNfWatcher,