1tube 0.1.21 → 0.1.23

package/deno.json

@@ -18,6 +18,7 @@
     "esbuild": "npm:esbuild@^0.28",
     "es-module-lexer": "npm:es-module-lexer@^2",
     "@deno/esbuild-plugin": "jsr:@deno/esbuild-plugin@^1.2",
+    "@deno/graph": "jsr:@deno/graph@^0.108",
     "@zip-js/zip-js": "jsr:@zip-js/zip-js@^2.8"
   },
   "lint": {

package/deno.lock

@@ -2,6 +2,7 @@
   "version": "5",
   "specifiers": {
     "jsr:@deno/esbuild-plugin@^1.2.0": "1.2.1",
+    "jsr:@deno/graph@0.108": "0.108.1",
     "jsr:@deno/loader@~0.3.10": "0.3.14",
     "jsr:@std/assert@1": "1.0.19",
     "jsr:@std/fs@1": "1.0.22",
@@ -10,7 +11,10 @@
     "jsr:@std/path@^1.1.1": "1.1.4",
     "jsr:@std/path@^1.1.4": "1.1.4",
     "jsr:@zip-js/zip-js@^2.8.0": "2.8.26",
+    "npm:@ai-sdk/anthropic@2": "2.0.77_zod@3.25.76",
+    "npm:@ai-sdk/google@2": "2.0.70_zod@3.25.76",
     "npm:@ai-sdk/mcp@0": "0.0.15_zod@3.25.76",
+    "npm:@ai-sdk/openai@2": "2.0.103_zod@3.25.76",
     "npm:@google/genai@1.39.0": "1.39.0",
     "npm:@supabase/supabase-js@2": "2.93.3",
     "npm:ai@6": "6.0.67_zod@3.25.76",
@@ -31,6 +35,9 @@
         "npm:esbuild@~0.25.5"
       ]
     },
+    "@deno/graph@0.108.1": {
+      "integrity": "10ba877ae62f94987f4465aa94c355612382456f64bb9b1b9c1b473559f294af"
+    },
     "@deno/loader@0.3.14": {
       "integrity": "97bc63a6cc2d27a60bcdc953f588c5213331d866d44212eebb24cebfb9b011ca"
     },
@@ -60,6 +67,14 @@
     }
   },
   "npm": {
+    "@ai-sdk/anthropic@2.0.77_zod@3.25.76": {
+      "integrity": "sha512-8n7ApEzFOxqVvT3HyqLrEQlgUx/2nUmPFLTGY3fNKwUA8KVNU3Ovd2C66Qh1Y93Iq5NkHsOWuLiTyAZpRKQhgw==",
+      "dependencies": [
+        "@ai-sdk/provider@2.0.1",
+        "@ai-sdk/provider-utils@3.0.23_zod@3.25.76",
+        "zod"
+      ]
+    },
     "@ai-sdk/gateway@3.0.32_zod@3.25.76": {
       "integrity": "sha512-7clZRr07P9rpur39t1RrbIe7x8jmwnwUWI8tZs+BvAfX3NFgdSVGGIaT7bTz2pb08jmLXzTSDbrOTqAQ7uBkBQ==",
       "dependencies": [
@@ -69,6 +84,14 @@
         "zod"
       ]
     },
+    "@ai-sdk/google@2.0.70_zod@3.25.76": {
+      "integrity": "sha512-NDMTvMo6vnPHDTA94FBOh3YMv0lxWDohYmFSGYhg0IimHMcOcC1ZV7E2KMLjzHOz5S7uasTITW7V3X5T+ozInQ==",
+      "dependencies": [
+        "@ai-sdk/provider@2.0.1",
+        "@ai-sdk/provider-utils@3.0.23_zod@3.25.76",
+        "zod"
+      ]
+    },
     "@ai-sdk/mcp@0.0.15_zod@3.25.76": {
       "integrity": "sha512-bjWQGNh7zplf0sqW1RnSF9HzKGo+fCvD5BPTSSA+Fw/on+OAI6S6rBc/KHBWNyjJbIZZ9XvT6WpGYKdZHaKqlA==",
       "dependencies": [
@@ -78,6 +101,14 @@
         "zod"
       ]
     },
+    "@ai-sdk/openai@2.0.103_zod@3.25.76": {
+      "integrity": "sha512-FDwY060LV/D5th+LeaxpSKcot5eXjzNzHguDf0NU1K+v7rxYZFWbldQPZarNo/IpD/WJE9RojgrFAcZ1e8KyvQ==",
+      "dependencies": [
+        "@ai-sdk/provider@2.0.1",
+        "@ai-sdk/provider-utils@3.0.23_zod@3.25.76",
+        "zod"
+      ]
+    },
     "@ai-sdk/provider-utils@3.0.22_zod@3.25.76": {
       "integrity": "sha512-fFT1KfUUKktfAFm5mClJhS1oux9tP2qgzmEZVl5UdwltQ1LO/s8hd7znVrgKzivwv1s1FIPza0s9OpJaNB/vHw==",
       "dependencies": [
@@ -87,6 +118,15 @@
         "zod"
       ]
     },
+    "@ai-sdk/provider-utils@3.0.23_zod@3.25.76": {
+      "integrity": "sha512-60GYsRj5wIJQRcq5YwYJq4KhwLeStceXEJiZdecP1miiH+6FMmrnc7lZDOJoQ6m9lrudEb+uI4LEwddLz5+rPQ==",
+      "dependencies": [
+        "@ai-sdk/provider@2.0.1",
+        "@standard-schema/spec",
+        "eventsource-parser",
+        "zod"
+      ]
+    },
     "@ai-sdk/provider-utils@4.0.13_zod@3.25.76": {
       "integrity": "sha512-HHG72BN4d+OWTcq2NwTxOm/2qvk1duYsnhCDtsbYwn/h/4zeqURu1S0+Cn0nY2Ysq9a9HGKvrYuMn9bgFhR2Og==",
       "dependencies": [
@@ -861,6 +901,7 @@
   "workspace": {
     "dependencies": [
       "jsr:@deno/esbuild-plugin@^1.2.0",
+      "jsr:@deno/graph@0.108",
       "jsr:@std/assert@1",
       "jsr:@std/path@1",
       "jsr:@zip-js/zip-js@^2.8.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1tube",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "private": false,
   "description": "Self-hosted Supabase Edge Functions gateway for Deno, plus an ESLint plugin for consumers",
   "license": "MIT",

package/src/backends/deno/dep-graph.ts

@@ -0,0 +1,233 @@
+/**
+ * Per-function dependency graph for the Deno backend's HMR.
+ *
+ * Wraps `jsr:@deno/graph` (the same module-graph engine the Deno CLI uses)
+ * to compute the set of `file://` URLs that each function transitively
+ * imports. With those graphs in hand, a single fs change maps to the exact
+ * set of functions whose Worker needs to be restarted — no more
+ * "anything under `_shared/` triggers a full reload" heuristic.
+ *
+ * Only `file://` URLs are tracked. `npm:`, `jsr:`, `https:` and `node:`
+ * deps cannot fire local fs watcher events, so they would never be
+ * "changed" anyway; including them in the reverse index is wasted RAM.
+ *
+ * Bare specifiers from `deno.json` `imports` are resolved through a
+ * tiny in-process import-map resolver (longest-prefix-wins, exact-match
+ * preferred). This is the Deno CLI's own algorithm reduced to its
+ * essentials — sufficient for typical edge-function projects.
+ *   import "@db/util"   →  imports: { "@db/util": "./_shared/util.ts" }
+ * resolves to the file URL the user actually edits, and the graph
+ * tracks it correctly.
+ */
+
+import { createGraph } from "@deno/graph";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// Local re-export for callers that prefer std/path-style names. Underlying
+// implementations come from node:url so this module loads from node_modules
+// in any host project without extra import-map plumbing.
+export { fileURLToPath, pathToFileURL };
+
+export interface DepGraphOptions {
+  /**
+   * Parsed `imports` field from the host project's deno.json. Used to
+   * resolve bare specifiers to file URLs when the user wires
+   * `_shared` etc. through an import map alias. Optional; if absent,
+   * only relative imports are tracked precisely.
+   */
+  importMap?: Readonly<Record<string, string>>;
+  /**
+   * Absolute path of the deno.json the import map came from. Import
+   * map values are resolved relative to this. Required when
+   * `importMap` is set.
+   */
+  importMapBase?: string;
+}
+
+export interface DepGraph {
+  /**
+   * Build (or rebuild) the graph for one function entry. Replaces any
+   * prior graph for `name`. Resolves once the graph is ready; transient
+   * graph errors (missing files mid-edit) are swallowed so a save
+   * burst with a half-written file doesn't crash the watcher.
+   */
+  refresh(name: string, entryFileUrl: string): Promise<void>;
+  /** Drop a function's graph. Used when an `index.ts` is deleted. */
+  forget(name: string): void;
+  /**
+   * Names whose graph contains any of `changedFiles`. Inputs are
+   * accepted as either absolute paths or `file://` URLs; both are
+   * normalized internally.
+   */
+  affected(changedFiles: Iterable<string>): Set<string>;
+  /** Total number of distinct file URLs currently tracked. */
+  readonly size: number;
+}
+
+/**
+ * Normalize a path-or-URL to a canonical `file:///...` string with
+ * forward-slash separators (matches what deno_graph emits for module
+ * specifiers). Falls back to the original string on parse failure so
+ * non-file specifiers aren't accidentally mangled.
+ */
+function normalize(pathOrUrl: string): string {
+  if (pathOrUrl.startsWith("file://")) return new URL(pathOrUrl).href;
+  try {
+    return pathToFileURL(pathOrUrl).href;
+  } catch {
+    return pathOrUrl;
+  }
+}
+
+/**
+ * Resolve `specifier` against `importMap` using the same prefix rules
+ * Deno applies. Returns the rewritten specifier or null when no entry
+ * matches.
+ */
+function applyImportMap(
+  specifier: string,
+  importMap: Readonly<Record<string, string>>,
+  base: string,
+): string | null {
+  const exact = importMap[specifier];
+  if (exact !== undefined) return resolveAgainst(exact, base);
+  let bestKey: string | null = null;
+  for (const key of Object.keys(importMap)) {
+    if (!key.endsWith("/")) continue;
+    if (!specifier.startsWith(key)) continue;
+    if (bestKey === null || key.length > bestKey.length) bestKey = key;
+  }
+  if (bestKey === null) return null;
+  const target = importMap[bestKey] + specifier.slice(bestKey.length);
+  return resolveAgainst(target, base);
+}
+
+function resolveAgainst(target: string, base: string): string {
+  // Bare URLs (npm:/jsr:/https:/file:) pass through unchanged. Relative
+  // paths get resolved against the import map's deno.json directory so
+  // `./_shared/x.ts` in deno.json points where the user expects.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target)) return target;
+  const baseUrl = base.startsWith("file://") ? base : pathToFileURL(base).href;
+  return new URL(target, baseUrl).href;
+}
+
+export function createDepGraph(options?: DepGraphOptions): DepGraph {
+  const perName = new Map<string, Set<string>>();
+  const reverse = new Map<string, Set<string>>();
+
+  const importMap = options?.importMap;
+  const importMapBase = options?.importMapBase;
+
+  const resolve = importMap && importMapBase
+    ? (specifier: string, referrer: string): string => {
+      const rewritten = applyImportMap(specifier, importMap, importMapBase);
+      if (rewritten !== null) return rewritten;
+      // Fall through to standard resolution against the referrer.
+      try {
+        return new URL(specifier, referrer).href;
+      } catch {
+        return specifier;
+      }
+    }
+    : undefined;
+
+  function indexAdd(name: string, fileUrl: string): void {
+    let set = reverse.get(fileUrl);
+    if (!set) {
+      set = new Set();
+      reverse.set(fileUrl, set);
+    }
+    set.add(name);
+  }
+
+  function indexRemove(name: string, fileUrl: string): void {
+    const set = reverse.get(fileUrl);
+    if (!set) return;
+    set.delete(name);
+    if (set.size === 0) reverse.delete(fileUrl);
+  }
+
+  return {
+    async refresh(name, entryFileUrl) {
+      const entry = normalize(entryFileUrl);
+      let graph;
+      try {
+        graph = await createGraph([entry], resolve ? { resolve } : undefined);
+      } catch {
+        // A save mid-flush can leave a syntactically broken file on
+        // disk; deno_graph throws. Drop the graph for `name` so the
+        // affected-set reverts to "this entry only" and let the next
+        // (clean) save rebuild it. Better than dying.
+        const old = perName.get(name);
+        if (old) {
+          for (const f of old) indexRemove(name, f);
+        }
+        const minimal = new Set<string>([entry]);
+        perName.set(name, minimal);
+        indexAdd(name, entry);
+        return;
+      }
+
+      const fresh = new Set<string>();
+      for (const mod of graph.modules ?? []) {
+        const spec: string | undefined = mod?.specifier;
+        if (typeof spec !== "string") continue;
+        if (!spec.startsWith("file://")) continue;
+        fresh.add(spec);
+      }
+      // Always include the entry, even if deno_graph short-circuited
+      // due to a load error on a child.
+      fresh.add(entry);
+
+      const old = perName.get(name);
+      if (old) {
+        for (const f of old) {
+          if (!fresh.has(f)) indexRemove(name, f);
+        }
+      }
+      for (const f of fresh) {
+        if (!old || !old.has(f)) indexAdd(name, f);
+      }
+      perName.set(name, fresh);
+    },
+
+    forget(name) {
+      const old = perName.get(name);
+      if (!old) return;
+      for (const f of old) indexRemove(name, f);
+      perName.delete(name);
+    },
+
+    affected(changedFiles) {
+      const out = new Set<string>();
+      for (const raw of changedFiles) {
+        const url = normalize(raw);
+        const owners = reverse.get(url);
+        if (!owners) continue;
+        for (const n of owners) out.add(n);
+      }
+      return out;
+    },
+
+    get size() {
+      return reverse.size;
+    },
+  };
+}
+
+/**
+ * Best-effort path resolver for paths that may have come from
+ * `Deno.watchFs` (which emits OS-native paths). Exposed for tests
+ * and callers that want to compare a file URL against a watched
+ * path without going through the graph.
+ */
+export function fileUrlOrPath(input: string): string {
+  if (input.startsWith("file://")) {
+    try {
+      return fileURLToPath(input);
+    } catch {
+      return input;
+    }
+  }
+  return input;
+}

package/src/backends/deno/hot-reloader.ts

@@ -0,0 +1,304 @@
+/**
+ * Hot reloader for the Deno backend (Worker-per-function model).
+ *
+ * The flow:
+ *
+ *     Deno.watchFs ─▶ pendingPaths set ─▶ debounce(200ms)
+ *                                              │
+ *                                              ▼
+ *                       affected = depGraph.affected(paths)
+ *                       affected ∪= names with index.ts created/deleted
+ *                                              │
+ *                                              ▼
+ *                                  host.reload(affected)
+ *
+ * The dep-graph (built and maintained by {@link DenoWorkerHost}) is the
+ * source of truth for "which function does this file belong to" — much
+ * more precise than the historical
+ * "first directory of the relative path, with `_*` promoted to full
+ * reload" heuristic used by the workerd backend.
+ *
+ * Two seams keep this testable without spinning up real Workers:
+ *
+ *   - {@link createDenoReloadDebouncer}: the pure debounce + flush
+ *     buffer, exported on its own so unit tests can drive it with a
+ *     fake clock and assert pending-set semantics.
+ *   - {@link createDenoHotReloader}: the loop that consumes a watcher
+ *     iterable. Tests pass an async iterator of fake events instead
+ *     of the real `Deno.watchFs` to avoid filesystem flake.
+ */
+
+import type { DenoWorkerHost, ReloadSummary } from "./worker-host.ts";
+import type { DepGraph } from "./dep-graph.ts";
+
+export type FsEventStream = AsyncIterable<{ paths: readonly string[] }> & {
+  close(): void;
+};
+
+export interface DenoHotReloaderOptions {
+  host: DenoWorkerHost;
+  functionsDir: string;
+  /** Defaults to 200ms — same as the workerd path. */
+  debounceMs?: number;
+  /** Test seam: factory for the watcher iterable. */
+  watch?: (dir: string) => FsEventStream;
+  /** Test seams for the debouncer's clock. */
+  setTimer?: (cb: () => void, ms: number) => number;
+  clearTimer?: (id: number) => void;
+  /** Override the log function (defaults to console.log). */
+  log?: (line: string) => void;
+  /** Optional hook fired after each reload, with the summary. */
+  onReloaded?: (summary: ReloadSummary) => void;
+}
+
+export interface DenoHotReloader {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+export interface DenoReloadDebouncer {
+  push(paths: readonly string[]): void;
+  cancel(): void;
+  /** Drain the pending-path set without flushing. Test seam. */
+  drain(): string[];
+  readonly isFlushing: boolean;
+}
+
+export interface DenoReloadDebouncerOptions {
+  debounceMs: number;
+  flushFn: (paths: readonly string[]) => Promise<void>;
+  setTimer?: (cb: () => void, ms: number) => number;
+  clearTimer?: (id: number) => void;
+}
+
+/**
+ * Path-set debouncer. Coalesces fs events arriving inside a single
+ * `debounceMs` window into one `flushFn` call carrying the union.
+ *
+ * If a flush is already in progress when the timer fires, it re-arms
+ * itself so changes saved during the in-flight reload aren't lost.
+ */
+export function createDenoReloadDebouncer(
+  opts: DenoReloadDebouncerOptions,
+): DenoReloadDebouncer {
+  const setTimer = opts.setTimer ??
+    ((cb, ms) => setTimeout(cb, ms) as unknown as number);
+  const clearTimer = opts.clearTimer ?? ((id) => clearTimeout(id));
+
+  const pending = new Set<string>();
+  let timerId: number | null = null;
+  let flushing = false;
+
+  const flush = async () => {
+    timerId = null;
+    if (flushing) return;
+    if (pending.size === 0) return;
+    const paths = [...pending];
+    pending.clear();
+    flushing = true;
+    try {
+      await opts.flushFn(paths);
+    } finally {
+      flushing = false;
+      if (pending.size > 0) {
+        if (timerId !== null) clearTimer(timerId);
+        timerId = setTimer(flush, opts.debounceMs);
+      }
+    }
+  };
+
+  return {
+    push(paths) {
+      let added = false;
+      for (const p of paths) {
+        if (!pending.has(p)) {
+          pending.add(p);
+          added = true;
+        }
+      }
+      if (!added) return;
+      if (timerId !== null) clearTimer(timerId);
+      timerId = setTimer(flush, opts.debounceMs);
+    },
+    cancel() {
+      if (timerId !== null) {
+        clearTimer(timerId);
+        timerId = null;
+      }
+    },
+    drain() {
+      const out = [...pending];
+      pending.clear();
+      return out;
+    },
+    get isFlushing() {
+      return flushing;
+    },
+  };
+}
+
+/**
+ * Compute the set of function names that need reloading given a batch
+ * of changed file paths and the current dep-graph. Exposed for tests.
+ *
+ * Three sources, in order of precision:
+ *
+ * 1. Files inside the dep-graph: their owners are affected. This is the
+ *    precise case — exactly the functions that transitively import the
+ *    changed file.
+ * 2. Files matching `<functionsDir>/<name>/index.ts`: include `<name>`.
+ *    Catches the entry's own edits.
+ * 3. Path is the directory `<functionsDir>/<name>` itself or any path
+ *    under it (subtree change). This is necessary for two cases the
+ *    other rules miss:
+ *      - **Linux**: `Deno.watchFs` is recursive only over the dirs
+ *        that existed at start. A *new* function dir reports a single
+ *        `<functionsDir>/<name>` create event — child file events
+ *        never fire because inotify doesn't auto-watch the new subdir.
+ *      - **Windows**: deleting a function dir tree emits dir-path
+ *        events instead of `index.ts` events.
+ *    Either way the affected name is the first path component after
+ *    `functionsDir`. We let `discoverCandidates` filter out junk
+ *    (e.g. `_shared`) on the reload pass so this rule stays simple
+ *    and doesn't need the host's knownNames set.
+ */
+export function computeAffected(
+  paths: readonly string[],
+  depGraph: DepGraph,
+  options: { functionsDir?: string } = {},
+): Set<string> {
+  const out = depGraph.affected(paths);
+  for (const p of paths) {
+    const m = /[\\/]([^\\/]+)[\\/]index\.ts$/.exec(p);
+    if (m && m[1]) out.add(m[1]);
+  }
+  if (options.functionsDir) {
+    const fnDir = options.functionsDir.replace(/[\\/]$/, "");
+    for (const p of paths) {
+      // Strip the prefix; anything left should look like
+      // `/<name>` or `/<name>/<rest>`. Cross-platform: try both
+      // separators and accept whichever the OS produced.
+      let rest: string | null = null;
+      if (p.startsWith(fnDir + "/")) rest = p.slice(fnDir.length + 1);
+      else if (p.startsWith(fnDir + "\\")) rest = p.slice(fnDir.length + 1);
+      else if (p === fnDir) continue;
+      if (rest === null) continue;
+      const seg = rest.split(/[\\/]/, 1)[0];
+      // Skip private/shared dirs the host already filters out — keeps
+      // the affected set tight even before `reload()` runs.
+      if (!seg || seg.startsWith("_") || seg.endsWith("_shared")) continue;
+      out.add(seg);
+    }
+  }
+  return out;
+}
+
+export function createDenoHotReloader(
+  opts: DenoHotReloaderOptions,
+): DenoHotReloader {
+  const log = opts.log ?? ((line) => console.log(line));
+  const watcherFactory = opts.watch ?? ((dir: string) =>
+    Deno.watchFs(dir, { recursive: true }) as unknown as FsEventStream
+  );
+
+  let stream: FsEventStream | null = null;
+  let stopped = false;
+  let consumeLoop: Promise<void> | null = null;
+
+  const debouncer = createDenoReloadDebouncer({
+    debounceMs: opts.debounceMs ?? 200,
+    setTimer: opts.setTimer,
+    clearTimer: opts.clearTimer,
+    flushFn: async (paths) => {
+      const raw = computeAffected(paths, opts.host.depGraph, {
+        functionsDir: opts.functionsDir,
+      });
+      // Filter to names that are either currently loaded or have an
+      // `index.ts` on disk right now. This drops spurious entries
+      // synthesized from non-function files at the root of
+      // `functionsDir` (README.md, .gitignore, …) so we don't spend
+      // a reload pass producing an empty summary.
+      const known = new Set(opts.host.list());
+      const affected = new Set<string>();
+      for (const name of raw) {
+        if (known.has(name)) {
+          affected.add(name);
+          continue;
+        }
+        try {
+          const indexPath = `${opts.functionsDir}/${name}/index.ts`;
+          const stat = await Deno.stat(indexPath);
+          if (stat.isFile) affected.add(name);
+        } catch {
+          // No index.ts → not a function; drop.
+        }
+      }
+      if (affected.size === 0) return;
+      const reason = `${affected.size} function(s) changed: ${
+        [...affected].sort().join(", ")
+      }`;
+      log(`[1tube] HMR ${reason}`);
+      try {
+        const summary = await opts.host.reload(affected, reason);
+        const parts: string[] = [];
+        if (summary.reloaded.length > 0) {
+          parts.push(`reloaded=${summary.reloaded.join(",")}`);
+        }
+        if (summary.added.length > 0) {
+          parts.push(`added=${summary.added.join(",")}`);
+        }
+        if (summary.removed.length > 0) {
+          parts.push(`removed=${summary.removed.join(",")}`);
+        }
+        log(
+          `[1tube] HMR reload ok in ${summary.durationMs.toFixed(0)}ms${
+            parts.length > 0 ? ` (${parts.join("; ")})` : ""
+          }`,
+        );
+        for (const e of summary.errors) {
+          log(`[1tube] HMR ${e.name}: ${e.error}`);
+        }
+        opts.onReloaded?.(summary);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(`[1tube] HMR reload FAILED — keeping previous workers alive. Error: ${msg}`);
+      }
+    },
+  });
+
+  return {
+    async start() {
+      if (stream) return;
+      stream = watcherFactory(opts.functionsDir);
+      log(`[1tube] HMR watching: ${opts.functionsDir}`);
+      consumeLoop = (async () => {
+        try {
+          for await (const event of stream!) {
+            if (stopped) break;
+            if (event.paths.length === 0) continue;
+            debouncer.push(event.paths);
+          }
+        } catch (err) {
+          if (!stopped) log(`[1tube] HMR watcher disabled: ${err}`);
+        }
+      })();
+    },
+    async stop() {
+      if (stopped) return;
+      stopped = true;
+      debouncer.cancel();
+      try {
+        stream?.close();
+      } catch { /* */ }
+      stream = null;
+      if (consumeLoop) {
+        let timeoutId: number | undefined;
+        const bound = new Promise<void>((resolve) => {
+          timeoutId = setTimeout(resolve, 250) as unknown as number;
+        });
+        await Promise.race([consumeLoop, bound]);
+        if (timeoutId !== undefined) clearTimeout(timeoutId);
+      }
+    },
+  };
+}