@graftland/hmr 0.1.0 → 0.2.0-beta.0

package/README.md

@@ -1,13 +1,161 @@
 # @graftland/hmr
 
+English |
+[简体中文](https://github.com/graftland/graft/blob/main/packages/hmr/README.zh-CN.md)
+|
+[繁體中文](https://github.com/graftland/graft/blob/main/packages/hmr/README.zh-TW.md)
+
 Reloads plugin modules on Node.js without restarting the process.
 
 ```sh
 npm install @graftland/hmr effect
 ```
 
-`Hmr.make` gives an importer for the loader, and `reload` and `watch` to replace
-plugins with new code. Needs Node.js 22.15 or later.
+`Hmr.make` gives you an importer for the loader. It also gives you `reload` and
+`watch`, which replace plugins with new code. It needs Node.js 22.19 or later.
+
+## Watching files
+
+`watch` uses native filesystem events, so reloads happen quickly. It also checks
+the contents of loaded, versioned modules inside the watched paths once per
+second. This catches changes that the native backend missed. For example:
+
+- the startup window of the macOS directory watcher
+- a save between an import and the watcher installation
+
+How the checks work:
+
+- A newly loaded module is compared with the bytes that its module hook read. So
+  adding a plugin through configuration does not count as a file change.
+- Each disk observation is tied to an import attempt and to the bytes that the
+  attempt actually read.
+- A newer committed or failed attempt makes older observations invalid. So a
+  save between a snapshot and an import cannot leave the running plugin on the
+  wrong version.
+- An unchanged failed attempt stays acknowledged until the next change. Polling
+  does not retry it again and again.
+- The check respects `recursive`. It stops when the consumer closes the stream.
+- Its cost depends on the contents of those modules, not on the size of the
+  directory tree.
+
+`watch(paths, options)` accepts `filter(absolutePath)` in addition to
+`recursive`, `onReady`, and `debounce`. The predicate filters both native events
+and periodic content checks. By default, every path is accepted. For example:
+
+```ts
+hmr.watch([directory], {
+	recursive: true,
+	filter: (path) => path.endsWith(".mjs"),
+})
+```
+
+The CLI uses this filter for JavaScript and TypeScript module files outside
+`node_modules`. YAML configuration changes belong to the loader. They never
+trigger an HMR reload of every entry.
+
+## Failures
+
+Debouncing does not make file writes atomic. If a reload meets incomplete code,
+it emits `Failed` with the original `Cause`. A later content change can start
+recovery, even without another native event.
+
+Watcher I/O failures and reconciliation I/O failures both fail the stream. So
+consumers should handle both failure channels.
+
+`onReady` reports that the watcher is installed. It is not an operating-system
+delivery barrier.
+
+## When a restart is needed
+
+CommonJS and native dependencies need a process restart. HMR tracks dependency
+facts by generation for the session. This includes dynamic imports during plugin
+activation, after the entry import completes. Once HMR records such a
+dependency, later reloads of that generation return `Skipped` with
+`restart-required`.
+
+Loading through `require` is not isolated by ESM URL versions. This includes
+`require(esm)`. HMR is careful here. It treats a versioned module's import of
+`node:module` (or `module`) as getting a native loading capability that it
+cannot track. That dependency graph returns `Skipped / restart-required`, even
+if the module only uses another utility from `node:module`. HMR records the
+capability before use. This covers CommonJS cache hits, and it stays valid when
+another entry gets the same capability. Use static or dynamic ESM imports for
+dependencies that need hot reload.
+
+Watchers report known native-loading restart requirements even without a file
+notification, including when a plugin acquires the capability after startup. The
+periodic status check suppresses unchanged reports. This warning does not mean
+that a reload occurred.
+
+Local file entry leases and their reachable dependency edges keep the requested
+path and its resolved target, together with the importing parent and generation.
+Reload checks this relationship before it imports, and again before it publishes
+any replacement. The same owned graph supplies polling, including dependencies
+from failed attempts awaiting retry; releasing the last lease removes its graph
+from these checks. If a symlink target changed, reload returns
+`Skipped / restart-required` with the affected request URLs. Every running
+plugin stays unchanged. Polling checks this relationship too. This includes
+targets with identical content and missed native events. Restart the process
+after you retarget an entry or helper. HMR does not invalidate Node's resolution
+caches. These checks cover local file requests in the tracked dependency graph.
+They do not cover changes to package export maps or bare-package resolution.
+
+## Entry leases
+
+`importerScoped(specifier)` is an Effect that needs `Scope`. Each call owns a
+lease on the entry. The last release removes the entry from later reloads.
+
+`importerScoped(specifier, { observationScope })` separates the observation
+lease from temporary importer resources. `ModuleResolver` passes this scope as
+the importer's second argument. Keep it alive while failed entries await retry,
+and close it when replacing the observation attempt or removing the entry.
+Candidate resources can close immediately on failure without deleting that
+observation. Omitting the option uses the caller's scope.
+
+The CLI passes this importer to `ModuleResolver`. Each configuration entry owns
+its observation scope independently of activation resources. A failed first
+import remains observable after candidate cleanup. Retrying replaces the old
+observation generation; removing or disabling the entry closes it.
+
+How polling and restarts work with leases:
+
+- Polling finds its file set from each live lease. It uses the running
+  generation and the latest uncommitted import attempt.
+- It keeps failed imports and missing local dependencies, so it can retry them.
+- It stops reading an entry, and the dependencies only that entry uses, when the
+  last owner closes.
+- A successful replacement retires the old dependency graph.
+- Only dependencies that can be reached from leased entries can require a
+  restart.
+- The Promise-based `importer` keeps its registrations until the HMR session
+  closes.
+
+## Replacement conflicts
+
+Sometimes entries shared one Plugin object, but now they export different
+objects. Then reload returns `Skipped` with reason `ambiguous-exports` and the
+affected module URLs.
+
+Two other cases return `Skipped` with reason `identity-conflict` and the
+conflicting module URLs:
+
+- Replacement identities overlap, such as `P → Q, Q → R`.
+- A mapping does not match the existing runtime aliases.
+
+In all of these cases, nothing is replaced. Restart the application, or restore
+a mapping that can be represented. Validation and alias publication share the
+core replacement transaction.
+
+Native watcher producers observe their complete Exit after source cleanup and
+before entering background stream merging. Mixed interruption failures are
+logged there with the full Cause; pure interruption is silent. Ordinary backend
+failures still propagate to the consumer without duplicate logging.
+
+## Cancellation
+
+When a module fails during cancellation, HMR records the original failure with
+its full Cause. It does this before pending interruption can hide the completed
+Exit.
 
 ## Documentation
 

package/README.zh-CN.md

@@ -0,0 +1,120 @@
+# @graftland/hmr
+
+[English](https://github.com/graftland/graft/blob/main/packages/hmr/README.md)
+| 简体中文 |
+[繁體中文](https://github.com/graftland/graft/blob/main/packages/hmr/README.zh-TW.md)
+
+在 Node.js 上热重载插件模块，无需重启进程。
+
+```sh
+npm install @graftland/hmr effect
+```
+
+`Hmr.make` 为加载器提供一个 importer，同时提供 `reload` 和
+`watch`，用新代码替换插件。需要 Node.js 22.19 或更高版本。
+
+## 监视文件
+
+`watch`
+使用原生文件系统事件，所以重载很快。它还会每秒检查一次监视路径内已加载的、带版本的模块的内容，以捕获原生后端漏掉的变更。例如：
+
+- macOS 目录监视器的启动窗口期
+- import 与监视器安装之间发生的保存
+
+检查的工作方式：
+
+- 新加载的模块会与它的模块钩子读取的字节进行比较。所以通过配置添加插件，不会被算作文件变更。
+- 每次磁盘观察都与一次 import 尝试以及该尝试实际读取的字节相关联。
+- 更新的已提交或已失败的尝试会使更早的观察失效。所以在快照与 import 之间发生的保存，不会让正在运行的插件停留在错误的版本上。
+- 未发生变化的失败尝试会保持已确认状态，直到下一次变更。轮询不会反复重试它。
+- 检查遵循 `recursive`，并在消费者关闭流时停止。
+- 它的开销取决于这些模块的内容，而不是目录树的大小。
+
+首次导入失败后，观察租约仍由配置项持有，与立即关闭的候选资源 scope 分离。修正模块后，即使原生通知丢失，也能通过轮询恢复。重试替换观察代次，移除或禁用配置项则关闭观察 scope。
+
+`watch(paths, options)` 除了 `recursive`、`onReady` 和 `debounce` 之外，还接受
+`filter(absolutePath)`。这个谓词同时过滤原生事件和定期的内容检查。默认接受所有路径。例如：
+
+```ts
+hmr.watch([directory], {
+	recursive: true,
+	filter: (path) => path.endsWith(".mjs"),
+})
+```
+
+CLI 对 `node_modules`
+之外的 JavaScript 和 TypeScript 模块文件使用这个过滤器。YAML 配置的变更属于加载器处理，永远不会触发对所有条目的 HMR 重载。
+
+## 失败
+
+防抖不会让文件写入变成原子操作。如果重载遇到不完整的代码，它会发出
+`Failed`，并带上原始的
+`Cause`。之后的内容变更可以触发恢复，即使没有新的原生事件。
+
+监视器 I/O 失败和对账 I/O 失败都会使流失败。所以消费者应该处理这两个失败通道。
+
+`onReady` 表示监视器已安装。它不是操作系统层面的事件投递屏障。
+
+## 何时需要重启
+
+CommonJS 和原生依赖需要重启进程。HMR 按会话的 generation 跟踪依赖信息，其中包括入口 import 完成之后、插件激活期间的动态 import。一旦 HMR 记录了这样的依赖，该 generation 之后的重载都会返回
+`Skipped`，原因是 `restart-required`。
+
+通过 `require` 加载的模块不受 ESM URL 版本的隔离，包括
+`require(esm)`。HMR 在这里很谨慎：带版本的模块只要 import 了 `node:module`（或
+`module`），HMR 就认为它获得了一种无法跟踪的原生加载能力。该依赖图会返回
+`Skipped / restart-required`，即使这个模块只用了 `node:module`
+里的其他工具。HMR 在使用之前就记录这种能力，这样可以覆盖 CommonJS 缓存命中的情况，并且在另一个入口获得同样的能力时仍然有效。需要热重载的依赖请使用静态或动态的 ESM
+import。
+
+即使没有文件通知，监听也会报告已知的原生加载重启要求，包括启动后才获取该能力的插件。周期性状态检查不会重复报告相同状态；这条警告不表示已经执行重载。
+
+本地文件入口及其可达依赖边会按代次保留请求路径、导入方和物理目标。入口和依赖共用检查逻辑及轮询数据；失败待重试的依赖图继续保留，最后一个租约释放后不再参与检查。重载在 import 之前检查这个关系，在发布任何替换之前再检查一次。如果符号链接的目标变了，重载会返回
+`Skipped / restart-required`，并附上受影响的请求 URL，所有正在运行的插件保持不变。轮询也会检查这个关系，包括内容相同的目标和漏掉的原生事件。重新指定入口或 helper 的目标之后，请重启进程。HMR 不会使 Node 的解析缓存失效。这些检查覆盖跟踪依赖图中的本地文件请求，不覆盖包的 export
+map 或裸包解析的变化。
+
+## 入口租约
+
+`importerScoped(specifier)` 是一个需要 `Scope`
+的 Effect。每次调用都持有该入口的一个租约。最后一个租约释放后，该入口不再参与之后的重载。
+
+`importerScoped(specifier, { observationScope })`
+将观察租约与候选导入的临时资源分开。`ModuleResolver`
+通过 importer 的第二个参数传递这个 scope。失败条目等待重试时应保留它，替换观察尝试或移除条目时关闭它；候选资源仍在失败时立即清理。省略该选项时使用调用方的 scope。
+
+原生 watcher 在源资源清理完成后、进入后台合并边界之前观察完整 Exit。包含失败的中断会在这里记录完整 Cause，纯中断保持安静；普通后端失败继续交给消费方处理，不重复记录。
+
+CLI 把这个 importer 传给
+`ModuleResolver`。它的入口 scope 在配置更新、激活失败或激活等待期间保持存活，并在入口被移除时关闭。
+
+轮询和重启如何与租约配合：
+
+- 轮询根据每个存活的租约确定文件集合，使用正在运行的 generation 和最近一次未提交的 import 尝试。
+- 它会保留失败的 import 和缺失的本地依赖，以便重试。
+- 当最后一个所有者关闭时，它不再读取该入口以及仅被该入口使用的依赖。
+- 成功的替换会让旧的依赖图退役。
+- 只有从被租用的入口可以到达的依赖，才可能要求重启。
+- 基于 Promise 的 `importer` 会保留它的注册，直到 HMR 会话关闭。
+
+## 替换冲突
+
+有时多个入口原本共享同一个 Plugin 对象，现在却导出了不同的对象。此时重载返回
+`Skipped`，原因是 `ambiguous-exports`，并附上受影响的模块 URL。
+
+另外两种情况会返回 `Skipped`，原因是 `identity-conflict`，并附上冲突的模块 URL：
+
+- 替换的标识有重叠，例如 `P → Q, Q → R`。
+- 映射与现有的运行时别名不一致。
+
+在所有这些情况下，都不会替换任何东西。请重启应用，或恢复一个可以表示的映射。校验与别名发布共用核心的替换事务。
+
+## 取消
+
+模块在取消期间失败时，HMR 会连同完整的 Cause 一起记录原始失败。它在待处理的中断掩盖已完成的 Exit 之前完成这一步。
+
+## 文档
+
+- [热重载](https://graftland.github.io/graft/zh-cn/hot-reload/)
+
+属于 [Graft](https://github.com/graftland/graft)。基于
+[Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE) 许可。

package/README.zh-TW.md

@@ -0,0 +1,120 @@
+# @graftland/hmr
+
+[English](https://github.com/graftland/graft/blob/main/packages/hmr/README.md) |
+[简体中文](https://github.com/graftland/graft/blob/main/packages/hmr/README.zh-CN.md)
+| 繁體中文
+
+在 Node.js 上熱重載外掛模組，不需要重新啟動行程。
+
+```sh
+npm install @graftland/hmr effect
+```
+
+`Hmr.make` 為載入器提供一個 importer，同時提供 `reload` 和
+`watch`，用新程式碼取代外掛。需要 Node.js 22.19 或更新版本。
+
+## 監看檔案
+
+`watch`
+使用原生檔案系統事件，所以重載很快。它還會每秒檢查一次監看路徑內已載入的、帶版本的模組的內容，以捕捉原生後端漏掉的變更。例如：
+
+- macOS 目錄監看器的啟動空窗期
+- import 與監看器安裝之間發生的儲存
+
+檢查的運作方式：
+
+- 新載入的模組會與它的模組鉤子讀取的位元組進行比較。所以透過設定新增外掛，不會被算作檔案變更。
+- 每次磁碟觀察都與一次 import 嘗試，以及該嘗試實際讀取的位元組相關聯。
+- 較新的已提交或已失敗的嘗試會使較舊的觀察失效。所以在快照與 import 之間發生的儲存，不會讓正在執行的外掛停留在錯誤的版本上。
+- 未發生變化的失敗嘗試會保持已確認狀態，直到下一次變更。輪詢不會反覆重試它。
+- 檢查遵循 `recursive`，並在消費者關閉串流時停止。
+- 它的開銷取決於這些模組的內容，而不是目錄樹的大小。
+
+`watch(paths, options)` 除了 `recursive`、`onReady` 和 `debounce` 之外，還接受
+`filter(absolutePath)`。這個謂詞同時過濾原生事件和定期的內容檢查。預設接受所有路徑。例如：
+
+```ts
+hmr.watch([directory], {
+	recursive: true,
+	filter: (path) => path.endsWith(".mjs"),
+})
+```
+
+CLI 對 `node_modules`
+之外的 JavaScript 和 TypeScript 模組檔案使用這個過濾器。YAML 設定的變更屬於載入器處理，永遠不會觸發對所有項目的 HMR 重載。
+
+## 失敗
+
+防抖動不會讓檔案寫入變成原子操作。如果重載遇到不完整的程式碼，它會發出
+`Failed`，並帶上原始的
+`Cause`。之後的內容變更可以觸發復原，即使沒有新的原生事件。
+
+監看器 I/O 失敗和對帳 I/O 失敗都會使串流失敗。所以消費者應該處理這兩個失敗通道。
+
+`onReady` 表示監看器已安裝。它不是作業系統層級的事件投遞屏障。
+
+## 何時需要重新啟動
+
+CommonJS 和原生相依套件需要重新啟動行程。HMR 依工作階段的 generation 追蹤相依資訊，其中包括入口 import 完成之後、外掛啟用期間的動態 import。一旦 HMR 記錄了這樣的相依套件，該 generation 之後的重載都會回傳
+`Skipped`，原因是 `restart-required`。
+
+透過 `require` 載入的模組不受 ESM URL 版本的隔離，包括
+`require(esm)`。HMR 在這裡很謹慎：帶版本的模組只要 import 了 `node:module`（或
+`module`），HMR 就認為它取得了一種無法追蹤的原生載入能力。該相依圖會回傳
+`Skipped / restart-required`，即使這個模組只用了 `node:module`
+裡的其他工具。HMR 在使用之前就記錄這種能力，這樣可以涵蓋 CommonJS 快取命中的情況，並且在另一個入口取得同樣的能力時仍然有效。需要熱重載的相依套件請使用靜態或動態的 ESM
+import。
+
+即使沒有檔案通知，監聽也會回報已知的原生載入重新啟動要求，包括啟動後才取得該能力的外掛。週期性狀態檢查不會重複回報相同狀態；這條警告不表示已經執行重載。
+
+本機檔案入口及其可達相依邊會按代次保留請求路徑、匯入方和實體目標。入口和相依檔案共用檢查邏輯及輪詢資料；失敗待重試的相依圖繼續保留，最後一個租約釋放後不再參與檢查。重載在 import 之前檢查這個關係，在發布任何取代之前再檢查一次。如果符號連結的目標變了，重載會回傳
+`Skipped / restart-required`，並附上受影響的請求 URL，所有正在執行的外掛保持不變。輪詢也會檢查這個關係，包括內容相同的目標和漏掉的原生事件。重新指定入口或 helper 的目標之後，請重新啟動行程。HMR 不會使 Node 的解析快取失效。這些檢查涵蓋追蹤相依圖中的本機檔案請求，不涵蓋套件的 export
+map 或裸套件解析的變化。
+
+## 入口租約
+
+`importerScoped(specifier)` 是一個需要 `Scope`
+的 Effect。每次呼叫都持有該入口的一個租約。最後一個租約釋放後，該入口不再參與之後的重載。
+
+首次匯入失敗後，觀察租約仍由設定項目持有，與立即關閉的候選資源 scope 分離。修正模組後，即使原生通知遺失，也能透過輪詢復原。重試會取代觀察代次，移除或停用設定項目則關閉觀察 scope。
+
+`importerScoped(specifier, { observationScope })`
+將觀察租約與候選匯入的暫時資源分開。`ModuleResolver`
+透過 importer 的第二個參數傳遞這個 scope。失敗項目等待重試時應保留它，取代觀察嘗試或移除項目時關閉它；候選資源仍在失敗時立即清理。省略此選項時使用呼叫端的 scope。
+
+原生 watcher 在來源資源清理完成後、進入背景合併邊界之前觀察完整 Exit。包含失敗的中斷會在這裡記錄完整 Cause，純中斷不記錄錯誤；一般後端失敗繼續交給消費端處理，不重複記錄。
+
+CLI 把這個 importer 傳給
+`ModuleResolver`。它的入口 scope 在設定更新、啟用失敗或啟用等待期間保持存活，並在入口被移除時關閉。
+
+輪詢和重新啟動如何與租約配合：
+
+- 輪詢根據每個存活的租約決定檔案集合，使用正在執行的 generation 和最近一次未提交的 import 嘗試。
+- 它會保留失敗的 import 和缺少的本機相依套件，以便重試。
+- 當最後一個擁有者關閉時，它不再讀取該入口以及僅被該入口使用的相依套件。
+- 成功的取代會讓舊的相依圖退役。
+- 只有從被租用的入口可以到達的相依套件，才可能要求重新啟動。
+- 以 Promise 為基礎的 `importer` 會保留它的註冊，直到 HMR 工作階段關閉。
+
+## 取代衝突
+
+有時多個入口原本共用同一個 Plugin 物件，現在卻匯出了不同的物件。此時重載回傳
+`Skipped`，原因是 `ambiguous-exports`，並附上受影響的模組 URL。
+
+另外兩種情況會回傳 `Skipped`，原因是 `identity-conflict`，並附上衝突的模組 URL：
+
+- 取代的識別有重疊，例如 `P → Q, Q → R`。
+- 對應與現有的執行期別名不一致。
+
+在所有這些情況下，都不會取代任何東西。請重新啟動應用程式，或還原成一個可以表示的對應。驗證與別名發布共用核心的取代交易。
+
+## 取消
+
+模組在取消期間失敗時，HMR 會連同完整的 Cause 一起記錄原始失敗。它在待處理的中斷掩蓋已完成的 Exit 之前完成這一步。
+
+## 文件
+
+- [熱重載](https://graftland.github.io/graft/zh-tw/hot-reload/)
+
+屬於 [Graft](https://github.com/graftland/graft)。依
+[Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE) 授權。

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Graft } from "@graftland/graft";
-import { Cause, Duration, Effect, FileSystem, PlatformError, Schema, Scope, Stream } from "effect";
+import { Cause, Data, Duration, Effect, FileSystem, PlatformError, Schema, Scope, Stream } from "effect";
 declare const HmrError_base: Schema.Class<HmrError, Schema.TaggedStruct<"HmrError", {
   readonly stage: Schema.Literals<readonly ["import", "exports", "closed"]>;
   readonly specifier: Schema.String;
@@ -10,33 +10,60 @@ declare const HmrError_base: Schema.Class<HmrError, Schema.TaggedStruct<"HmrErro
 export declare class HmrError extends HmrError_base {
   get message(): string;
 }
-export type ReloadResult = {
+export type WatchResult = Data.TaggedEnum<{
+  Reloaded: {
+    readonly entries: ReadonlyArray<string>;
+  };
+  Skipped: {
+    readonly modules: ReadonlyArray<string>;
+    readonly reason: "restart-required" | "ambiguous-exports" | "identity-conflict";
+  };
+  Failed: {
+    readonly cause: Cause.Cause<HmrError>;
+  };
+}>;
+export declare const WatchResult: Data.TaggedEnum.Constructor<{
+  readonly _tag: "Failed";
+  readonly cause: Cause.Cause<HmrError>;
+} | {
   readonly _tag: "Reloaded";
   readonly entries: ReadonlyArray<string>;
 } | {
   readonly _tag: "Skipped";
   readonly modules: ReadonlyArray<string>;
-  readonly reason: "restart-required";
-};
-export type WatchResult = ReloadResult | {
+  readonly reason: "restart-required" | "ambiguous-exports" | "identity-conflict";
+}>;
+export type ReloadResult = Exclude<WatchResult, {
   readonly _tag: "Failed";
-  readonly cause: Cause.Cause<HmrError>;
-};
+}>;
 export interface Options {
   /** Application module URL, usually import.meta.url; used for bare and relative resolution. */
   readonly base: string;
   /** Files to version. Defaults to file URLs outside node_modules. Entries are always included. */
   readonly include?: (url: string) => boolean;
 }
+export interface WatchOptions extends FileSystem.WatchOptions {
+  readonly debounce?: Duration.Input;
+  /** Receives an absolute file path; applies to native events and reconciliation. */
+  readonly filter?: (path: string) => boolean;
+}
+/** Separates retry observations from an importer's temporary resource scope. */
+export interface ImportOptions {
+  readonly observationScope: Scope.Scope;
+}
 export interface Hmr {
-  /** Pass directly to ModuleResolver.layer({ base, importer }). */
+  /** Keeps imported entries registered until this HMR session closes. */
   readonly importer: (specifier: string) => Promise<unknown>;
+  /** Registers an observation lease in observationScope, or the caller's scope when omitted. */
+  readonly importerScoped: (specifier: string, options?: ImportOptions) => Effect.Effect<unknown, HmrError, Scope.Scope>;
   /** Imports every entry before replacing anything. Activation failures belong to Graft. */
   readonly reload: Effect.Effect<ReloadResult, HmrError>;
-  /** Consuming this stream installs the watchers; the consumer owns their lifetime. */
-  readonly watch: (paths: ReadonlyArray<string>, options?: FileSystem.WatchOptions & {
-    readonly debounce?: Duration.Input;
-  }) => Stream.Stream<WatchResult, PlatformError.PlatformError, FileSystem.FileSystem>;
+  /**
+   * Consuming this stream installs watchers and checks loaded module contents once
+   * per second to recover missed events. Known native loading limitations emit
+   * Skipped even without a file event. The consumer owns the stream's lifetimes.
+   */
+  readonly watch: (paths: ReadonlyArray<string>, options?: WatchOptions) => Stream.Stream<WatchResult, PlatformError.PlatformError, FileSystem.FileSystem>;
 }
 /**
  * Installs Node module hooks until the enclosing scope closes. Module evaluation

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;WAwBmB;;qBAFN,iBAAiB;MAQhB;;YAKF;WACE;WAA2B,SAAS;;WAEtC;WACA,SAAS;WACT;;YAGA,cACT;WAES;WACA,OAAO,MAAM,MAAM;;iBAGd;;WAEP;;WAEA,WAAW;;iBAGJ;;WAEP,WAAW,sBAAsB;;WAEjC,QAAQ,OAAO,OAAO,cAAc;;WAEpC,QACR,OAAO,uBACP,UAAU,WAAW;aAA0B,WAAW,SAAS;QAC/D,OAAO,OACX,aACA,cAAc,eACd,WAAW;;;;;;qBAQA,OAAI,SACP,YACP,OAAO,OAAO,YAAY,MAAM,QAAQ,MAAM"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;WAsCmB;;qBAFN,iBAAiB;MAQhB;;YAKF,cAAc,KAAK;EAC9B;aAAqB,SAAS;;EAC9B;aACU,SAAS;aACT;;EAGV;aAAmB,OAAO,MAAM,MAAM;;;qBAG1B,aAAW,KAAA,WAAA;;WAHG,OAAA,MAAM,MAAM;;;WANR,SAAA;;;WAEX,SAAA;WAEjB;;YAOS,eAAe,QAAQ;WAAwB;;iBAE1C;;WAEP;;WAEA,WAAW;;iBAGJ,qBAAqB,WAAW;WACvC,WAAW,SAAS;;WAEpB,UAAU;;;iBAIH;WACP,kBAAkB,MAAM;;iBAGjB;;WAEP,WAAW,sBAAsB;;WAEjC,iBACR,mBACA,UAAU,kBACN,OAAO,gBAAgB,UAAU,MAAM;;WAEnC,QAAQ,OAAO,OAAO,cAAc;;;;;;WAMpC,QACR,OAAO,uBACP,UAAU,iBACN,OAAO,OACX,aACA,cAAc,eACd,WAAW;;;;;;qBAQA,OAAI,SACP,YACP,OAAO,OAAO,YAAY,MAAM,QAAQ,MAAM"}