tina4-nodejs 3.13.35 → 3.13.37

package/packages/core/src/devAdmin.ts

@@ -665,14 +665,37 @@ const handleReload: RouteHandler = async (req, res) => {
     const { rediscoverRoutes } = await import("./routeDiscovery.js");
     const newRoutes = await rediscoverRoutes();
     if (newRoutes.length > 0) {
-      const { defaultRouter } = await import("./router.js");
-      for (const route of newRoutes) defaultRouter.addRoute(route);
-      console.log(`  Re-discovered ${newRoutes.length} new route(s) on reload`);
+      // Add to the LIVE server router — startServer() builds a fresh Router and
+      // exposes it as globalThis.__tina4_router; that's the instance dispatch
+      // matches against. Adding to defaultRouter would land the re-imported
+      // handler in a table nobody serves from, so the stale route keeps winning
+      // (an edited route would never hot-reload). addRoute() replaces by pattern,
+      // so the fresh handler overwrites the old one in place. Fall back to
+      // defaultRouter when no server is running (e.g. unit tests).
+      const liveRouter = (globalThis as any).__tina4_router;
+      const target = liveRouter ?? (await import("./router.js")).defaultRouter;
+      for (const route of newRoutes) target.addRoute(route);
+      console.log(`  Re-discovered ${newRoutes.length} route(s) on reload`);
     }
   } catch (err) {
     console.error(`  Re-discover on reload failed:`, err);
   }
 
+  // WebSocket-primary reload: push an instant message to every browser
+  // connected on /__dev_reload. The toolbar client (and the dev-admin
+  // dashboard) act on this immediately — the mtime poll is only a fallback for
+  // when the socket is down. CSS changes swap stylesheets; everything else
+  // triggers a full page reload, so we normalise the wire `type` to
+  // "css"/"reload". The HTTP response still echoes the caller's original type.
+  // Wrapped so a broadcast failure (or zero clients) never 500s the endpoint.
+  const wsType = reloadType === "css" ? "css" : "reload";
+  try {
+    const { devReloadWs } = await import("./websocket.js");
+    devReloadWs.broadcast(JSON.stringify({ type: wsType, file: _reloadFile, mtime: _reloadMtime }));
+  } catch (err) {
+    console.error(`  Dev-reload WebSocket broadcast failed:`, err);
+  }
+
   res.json({ ok: true, type: reloadType });
 };
 
@@ -1734,37 +1757,196 @@ const handleExecute: RouteHandler = async (req, res) => {
   }
 };
 
-const handleFiles: RouteHandler = (req, res) => {
+// --- file-browser noise filter + git decoration (mirrors PHP/Python dev-admin) ---
+const DEV_FILES_IGNORED = new Set([
+  "__pycache__", "node_modules", "vendor", ".git",
+  "venv", ".venv", "dist", "target", ".tina4",
+]);
+
+// Hidden dot-entries are filtered too, except the env files.
+function devFilesHidden(name: string): boolean {
+  if (DEV_FILES_IGNORED.has(name)) return true;
+  return name.startsWith(".") && name !== ".env" && name !== ".env.example";
+}
+
+// Same 4-status mapping Python/PHP use for a porcelain code.
+function devGitStatusLabel(code: string): string {
+  if (code === "??") return "untracked";
+  if (code.includes("M")) return "modified";
+  if (code.includes("A")) return "added";
+  if (code.includes("D")) return "deleted";
+  return "clean";
+}
+
+/**
+ * Branch + porcelain status map for the file browser, mirroring PHP's
+ * devAdminGit* helpers 1:1. Paths git reports are relative to the repo
+ * root (always forward-slash); the project root may sit inside a larger
+ * repo (monorepo), so the toplevel is returned too for rebasing. Degrades
+ * to empty (every entry "clean") on any error / no git.
+ */
+async function devGitInfo(root: string): Promise<{ branch: string; gitRoot: string | null; status: Map<string, string> }> {
+  const empty = { branch: "", gitRoot: null as string | null, status: new Map<string, string>() };
+  try {
+    const { execFileSync } = await import("node:child_process");
+    const git = (args: string[]): string | null => {
+      try {
+        return execFileSync("git", args, { cwd: root, timeout: 3000, encoding: "utf-8" }).toString();
+      } catch {
+        return null;
+      }
+    };
+    const inside = git(["rev-parse", "--is-inside-work-tree"]);
+    if (!inside || inside.trim() !== "true") return empty;
+    const branch = (git(["rev-parse", "--abbrev-ref", "HEAD"]) ?? "").trim();
+    const topRaw = git(["rev-parse", "--show-toplevel"]);
+    const gitRoot = topRaw && topRaw.trim() !== ""
+      ? topRaw.trim().replace(/\\/g, "/").replace(/\/+$/, "")
+      : null;
+    const status = new Map<string, string>();
+    const porcelain = git(["status", "--porcelain", "-uall"]);
+    if (porcelain) {
+      for (const line of porcelain.split(/\r?\n/)) {
+        if (line.length < 4) continue;
+        const code = line.slice(0, 2).trim();
+        let p = line.slice(3).trim();
+        const arrow = p.indexOf(" -> ");      // rename/copy — keep destination
+        if (arrow !== -1) p = p.slice(arrow + 4);
+        if (p === "") continue;
+        status.set(p, code);
+      }
+    }
+    return { branch, gitRoot, status };
+  } catch {
+    return empty;
+  }
+}
+
+const handleFiles: RouteHandler = async (req, res) => {
+  // Response shape matches tina4-python / tina4-php 1:1 so the dev-admin SPA
+  // works against every framework with no branching: each entry carries
+  // `is_dir`, `has_children`, `git_status` and `size`; the payload carries the
+  // git `branch`. Noise dirs + hidden dot-files (except .env/.env.example) are
+  // filtered out.
   const url = new URL(req.url ?? "/", "http://localhost");
   const rel = url.searchParams.get("path") ?? ".";
   const root = resolve(process.cwd());
   const target = safeJoin(root, rel);
-  if (!target || !existsSync(target)) {
-    res.json({ error: `Path not found: ${rel}` }, 404);
+  const { branch, gitRoot, status: gitStatus } = await devGitInfo(root);
+
+  // Missing/invalid paths return an empty-but-valid shape (not 404): the SPA
+  // restores expanded-folder state from localStorage, and folders that don't
+  // exist in this harness would otherwise spam the console with red 404s.
+  if (!target || !existsSync(target) || !statSync(target).isDirectory()) {
+    res.json({ path: rel, branch, entries: [], error: "not a directory" });
     return;
   }
-  const stat = statSync(target);
-  if (!stat.isDirectory()) {
-    res.json({ error: `Not a directory: ${rel}` }, 400);
-    return;
+
+  // Rebase entry paths onto the git repo root when the project sits inside a
+  // larger repo. Everything runs in forward-slash form.
+  const rootFwd = root.replace(/\\/g, "/");
+  let cwdInGit = "";
+  if (gitRoot && gitRoot !== rootFwd && rootFwd.startsWith(gitRoot)) {
+    cwdInGit = rootFwd.slice(gitRoot.length).replace(/^\/+/, "");
+    if (cwdInGit !== "") cwdInGit += "/";
   }
-  const entries = readdirSync(target, { withFileTypes: true })
-    .filter((e) => !e.name.startsWith(".") || e.name === ".env")
-    .map((e) => {
-      const full = join(target, e.name);
-      let size = 0;
-      try { size = e.isFile() ? statSync(full).size : 0; } catch { /* ignore */ }
-      return {
-        name: e.name,
-        type: e.isDirectory() ? "dir" : "file",
-        size,
-        path: relative(root, full),
-      };
-    })
-    .sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name) : a.type === "dir" ? -1 : 1));
-  res.json({ path: relative(root, target) || ".", entries });
+
+  const entries: Array<Record<string, unknown>> = [];
+  for (const name of readdirSync(target).sort()) {   // alphabetical; no re-sort by type
+    if (devFilesHidden(name)) continue;
+    const full = join(target, name);
+    const entryRel = relative(root, full).replace(/\\/g, "/");
+
+    let isDir = false;
+    let size: number | null = null;
+    try {
+      const st = statSync(full);
+      isDir = st.isDirectory();
+      if (!isDir) size = st.size;
+    } catch { /* unreadable entry */ }
+
+    // git status for this entry (same mapping PHP/Python use)
+    const gitPath = cwdInGit + entryRel;
+    let gitLabel = "clean";
+    const code = gitStatus.get(gitPath);
+    if (code !== undefined) {
+      gitLabel = devGitStatusLabel(code);
+    } else if (isDir) {
+      const prefix = gitPath + "/";          // propagate dirty status from any child
+      for (const [gf, gc] of gitStatus) {
+        if (gf.startsWith(prefix)) { gitLabel = gc === "??" ? "untracked" : "modified"; break; }
+      }
+    }
+
+    // has_children: does the dir contain anything visible?
+    let hasChildren: boolean | null = null;
+    if (isDir) {
+      hasChildren = false;
+      try {
+        for (const c of readdirSync(full)) {
+          if (devFilesHidden(c)) continue;
+          hasChildren = true;
+          break;
+        }
+      } catch { /* ignore */ }
+    }
+
+    entries.push({
+      name,
+      path: entryRel,
+      is_dir: isDir,
+      has_children: hasChildren,
+      git_status: gitLabel,
+      size,
+    });
+  }
+
+  res.json({ path: relative(root, target).replace(/\\/g, "/") || ".", branch, entries });
+};
+
+// Canonical extension→language map. Kept identical in coverage to the Python
+// master (tina4_python/tina4_python/dev_admin/__init__.py `lang_map`) and the
+// PHP/Ruby file-read endpoints. The dev-admin SPA maps the returned "language"
+// string to a CodeMirror grammar for syntax highlighting.
+const DEV_ADMIN_LANG_MAP: Record<string, string> = {
+  ".py": "python", ".php": "php", ".rb": "ruby",
+  ".ts": "typescript", ".js": "javascript", ".jsx": "javascript",
+  ".tsx": "typescript", ".json": "json", ".html": "html",
+  ".twig": "html", ".css": "css", ".scss": "css",
+  ".md": "markdown", ".sql": "sql", ".yaml": "yaml",
+  ".yml": "yaml", ".toml": "toml", ".xml": "html",
+  ".env": "env", ".env.example": "env",
+  ".sh": "shell", ".bash": "shell",
+  ".bat": "shell", ".cmd": "shell", ".ps1": "shell",
+  ".rs": "rust", ".go": "go", ".java": "java",
+  ".txt": "text", ".csv": "text", ".log": "text",
+  ".gemspec": "ruby", ".rake": "ruby",
+  ".svg": "svg",
 };
 
+/**
+ * Resolve a CodeMirror-friendly language id from a file path's basename.
+ *
+ * - `Dockerfile` / `Dockerfile.dev` / `Dockerfile.prod` (no extension) → "dockerfile"
+ * - `.env.example` (two-part) and `.env` → "env"
+ * - otherwise the file extension is looked up in DEV_ADMIN_LANG_MAP
+ * - anything unknown → "text"
+ */
+export function devAdminLanguage(rel: string): string {
+  const base = (rel.split(/[\\/]/).pop() ?? "").toLowerCase();
+  if (base === "dockerfile" || base === "dockerfile.dev" || base === "dockerfile.prod") {
+    return "dockerfile";
+  }
+  // Two-part extension first (e.g. ".env.example"), then the single extension.
+  if (base.endsWith(".env.example")) return DEV_ADMIN_LANG_MAP[".env.example"];
+  const dot = base.lastIndexOf(".");
+  // A leading dot with no other dot is a dotfile name, not an extension
+  // (e.g. ".env" → ext ".env"); only treat as "no extension" when there's no dot.
+  if (dot < 0) return "text";
+  const ext = base.slice(dot);
+  return DEV_ADMIN_LANG_MAP[ext] ?? "text";
+}
+
 const handleFileRead: RouteHandler = (req, res) => {
   const url = new URL(req.url ?? "/", "http://localhost");
   const rel = url.searchParams.get("path") ?? "";
@@ -1776,7 +1958,8 @@ const handleFileRead: RouteHandler = (req, res) => {
   }
   try {
     const content = readFileSync(target, "utf-8");
-    res.json({ path: relative(root, target), content, bytes: Buffer.byteLength(content, "utf-8") });
+    const path = relative(root, target);
+    res.json({ path, content, language: devAdminLanguage(path), bytes: Buffer.byteLength(content, "utf-8") });
   } catch (e) {
     res.json({ error: (e as Error).message }, 500);
   }
@@ -2397,5 +2580,68 @@ function tina4VersionModal(){
         el.style.color='#f38ba8';
     });
 }
+</script>
+<script>
+(function(){
+    // WebSocket-primary dev reloader. The running server re-imports changed
+    // src/ routes in-process and pushes a {type,file,mtime} message over
+    // /__dev_reload — no respawn, instant refresh. The mtime poll below is a
+    // FALLBACK only, started when the socket is down and stopped on connect.
+    var _t4_css_exts=['.css','.scss'],_t4_debounce=null;
+    var _t4_interval=3000;
+    var _t4_ws=null,_t4_poll_timer=null,_t4_mtime=null;
+    function _t4_apply(d){
+        d=d||{};
+        var f=d.file||'',t=d.type||'';
+        var isCss=t==='css'||_t4_css_exts.some(function(e){return f.endsWith(e)});
+        if(isCss){
+            var links=document.querySelectorAll('link[rel="stylesheet"]');
+            links.forEach(function(l){
+                var href=l.getAttribute('href');
+                if(href){l.setAttribute('href',href.split('?')[0]+'?_t4='+(d.mtime||Date.now()))}
+            });
+        }else{
+            location.reload();
+        }
+    }
+    function _t4_poll(){
+        fetch('/__dev/api/mtime').then(function(r){return r.json()}).then(function(d){
+            // Sentinel: first poll only records the baseline. Use !== (not >) so
+            // the first change after load is not swallowed and a counter reset on
+            // server restart still triggers a reload.
+            if(_t4_mtime===null){_t4_mtime=d.mtime;return;}
+            if(d.mtime!==_t4_mtime){
+                _t4_mtime=d.mtime;
+                if(_t4_debounce)clearTimeout(_t4_debounce);
+                _t4_debounce=setTimeout(function(){_t4_apply(d);},500);
+            }
+        }).catch(function(){});
+    }
+    function _t4_startPoll(){
+        if(_t4_poll_timer)return;
+        _t4_mtime=null;
+        _t4_poll_timer=setInterval(_t4_poll,_t4_interval);
+    }
+    function _t4_stopPoll(){
+        if(_t4_poll_timer){clearInterval(_t4_poll_timer);_t4_poll_timer=null;}
+    }
+    function _t4_connect(){
+        var url=(location.protocol==='https:'?'wss':'ws')+'://'+location.host+'/__dev_reload';
+        try{_t4_ws=new WebSocket(url);}catch(_){_t4_startPoll();return;}
+        _t4_ws.addEventListener('open',function(){_t4_stopPoll();});
+        _t4_ws.addEventListener('message',function(ev){
+            var d=null;
+            try{d=typeof ev.data==='string'?JSON.parse(ev.data):null;}catch(_){}
+            if(!d)return;
+            if(d.type==='reload'||d.type==='change'||d.type==='css'){
+                if(_t4_debounce)clearTimeout(_t4_debounce);
+                _t4_debounce=setTimeout(function(){_t4_apply(d);},150);
+            }
+        });
+        _t4_ws.addEventListener('close',function(){_t4_ws=null;_t4_startPoll();setTimeout(_t4_connect,2000);});
+        _t4_ws.addEventListener('error',function(){try{_t4_ws&&_t4_ws.close();}catch(_){}});
+    }
+    _t4_connect();
+})();
 </script>`;
 }

package/packages/core/src/index.ts

@@ -61,6 +61,7 @@ export { GraphQL, ParseError, graphqlEndpoint, graphqlAutoSchemaEnabled } from "
 export type { GraphQLField, ResolverFn, GraphQLResult } from "./graphql.js";
 export {
   WebSocketServer,
+  devReloadWs,
   computeAcceptKey, parseUpgradeHeaders, buildFrame, parseFrame,
   OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG,
   CLOSE_NORMAL, CLOSE_PROTOCOL_ERROR,
@@ -73,7 +74,7 @@ export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api } from "./api.js";
 export type { ApiResult } from "./api.js";
 export { Events } from "./events.js";
-export { DevAdmin, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore, DevQueue, WsTracker, supervisorBaseUrl } from "./devAdmin.js";
+export { DevAdmin, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore, DevQueue, WsTracker, supervisorBaseUrl, devAdminLanguage } from "./devAdmin.js";
 export {
   feedbackEnabled,
   feedbackWhitelist,

package/packages/core/src/routeDiscovery.ts

@@ -11,6 +11,15 @@ const VALID_METHODS = new Set(["get", "post", "put", "delete", "patch"]);
  */
 const _seenFiles = new Set<string>();
 
+/**
+ * Last-seen mtime (ms) per route file. A file is (re)imported when it is new
+ * OR its mtime has increased since the previous scan — so editing an existing
+ * route file hot-reloads its handler instead of serving the stale one. The
+ * mtime also drives the import cache-bust query, so unchanged files don't
+ * needlessly re-execute.
+ */
+const _seenMtimes = new Map<string, number>();
+
 /** The last directory passed to discoverRoutes() — used by rediscoverRoutes(). */
 let _lastRoutesDir = "";
 
@@ -31,15 +40,20 @@ export async function discoverRoutes(routesDir: string): Promise<RouteDefinition
 
     routeFileCount++;
 
-    if (_seenFiles.has(filePath)) continue;
+    // Skip ONLY if we've already imported this exact file at its current mtime.
+    // A new file (not in _seenFiles) or an edited one (mtime increased) falls
+    // through and gets re-imported, so a hot-reload picks up the new handler.
+    const currentMtime = statSync(filePath).mtimeMs;
+    if (_seenFiles.has(filePath) && _seenMtimes.get(filePath) === currentMtime) continue;
 
     const method = name.toUpperCase();
     const relativePath = relative(routesDir, filePath);
     const pattern = filePathToPattern(relativePath);
 
     try {
-      // Cache-bust for hot-reload
-      const moduleUrl = `file://${filePath}?t=${Date.now()}`;
+      // Cache-bust for hot-reload, keyed on mtime: identical content reuses the
+      // same module URL (no needless re-import), an edit produces a fresh URL.
+      const moduleUrl = `file://${filePath}?t=${currentMtime}`;
       const mod = await import(moduleUrl);
 
       const handler: RouteHandler = mod.default ?? mod.handler;
@@ -53,6 +67,7 @@ export async function discoverRoutes(routesDir: string): Promise<RouteDefinition
 
       definitions.push({ method, pattern, handler, filePath, meta, template });
       _seenFiles.add(filePath);
+      _seenMtimes.set(filePath, currentMtime);
       registeredFromThisScan++;
     } catch (err) {
       console.error(`  Error loading route ${relativePath}:`, err);
@@ -76,8 +91,10 @@ export async function discoverRoutes(routesDir: string): Promise<RouteDefinition
 
 /**
  * Re-run the most recent route scan — called by POST /__dev/api/reload so a
- * newly-added file in src/routes/ registers without a server restart. Already
- * loaded files are skipped. No-op if discoverRoutes() has never been called.
+ * newly-added OR edited file in src/routes/ registers without a server restart.
+ * A file is re-imported when it's new or its mtime increased; unchanged files
+ * are skipped. The router replaces routes by pattern, so a re-imported route
+ * overwrites the stale handler. No-op if discoverRoutes() has never been called.
  */
 export async function rediscoverRoutes(): Promise<RouteDefinition[]> {
   if (!_lastRoutesDir) return [];
@@ -87,6 +104,7 @@ export async function rediscoverRoutes(): Promise<RouteDefinition[]> {
 /** Test-only: reset the seen-files state so tests can replay the same dir. */
 export function _resetRouteDiscovery(): void {
   _seenFiles.clear();
+  _seenMtimes.clear();
   _lastRoutesDir = "";
 }
 

package/packages/core/src/server.ts

@@ -18,7 +18,8 @@ import { loadEnv, isTruthy } from "./dotenv.js";
 import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
-import { DevAdmin, RequestInspector } from "./devAdmin.js";
+import { DevAdmin, RequestInspector, WsTracker } from "./devAdmin.js";
+import { devReloadWs } from "./websocket.js";
 import { feedbackEnabled, injectFeedbackWidget } from "./feedback.js";
 import { I18n } from "./i18n.js";
 import { stopAllBackgroundTasks } from "./background.js";
@@ -1392,6 +1393,32 @@ ${reset}
   // posts /__dev/api/reload to the MAIN port. Matches Python (master).
   const server = createServer(dispatch);
 
+  // WebSocket-primary DevReload: accept and hold /__dev_reload upgrades on the
+  // MAIN port (debug only) so POST /__dev/api/reload can push an instant reload.
+  // Mirrors Python's _register_dev_reload_ws + _ws_manager.broadcast(path=…).
+  // Without this the handshake 404s and the whole stack silently falls back to
+  // polling. Track connections in WsTracker so they appear in the dev-admin list.
+  if (isDevMode()) {
+    devReloadWs.setTracker(
+      (remoteAddress, p) => WsTracker.add(remoteAddress, p),
+      (id) => { WsTracker.remove(id); },
+    );
+    server.on("upgrade", (req: IncomingMessage, socket, head) => {
+      const upPath = (req.url ?? "/").split("?")[0];
+      if (upPath === "/__dev_reload") {
+        devReloadWs.handleUpgrade(req, socket, head);
+        return;
+      }
+      // Not a dev-reload upgrade — refuse cleanly rather than leaving it hanging.
+      try {
+        socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+        socket.destroy();
+      } catch {
+        /* socket already gone */
+      }
+    });
+  }
+
   return new Promise((resolvePromise) => {
     server.listen(port, host, () => {
       const displayHost = host === "0.0.0.0" ? "localhost" : host;
@@ -1420,6 +1447,17 @@ ${reset}
           await dispatch(req, res);
         });
 
+        // Stable AI port never accepts /__dev_reload (or any) WS upgrade — an AI
+        // tool driving it must never get a reload channel that its own edits trip.
+        aiServer.on("upgrade", (_req: IncomingMessage, socket) => {
+          try {
+            socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+            socket.destroy();
+          } catch {
+            /* socket already gone */
+          }
+        });
+
         aiServer.on("error", (err: any) => {
           if (err.code === "EADDRINUSE") {
             Log.warn(`Test port ${testPort} in use — skipping`);

package/packages/core/src/websocket.ts

@@ -562,3 +562,142 @@ export class WebSocketServer {
     this.clientRooms.delete(clientId);
   }
 }
+
+// ── Dev-reload WebSocket manager ─────────────────────────────
+
+/** A single accepted /__dev_reload socket plus its dashboard tracker id. */
+interface DevReloadClient {
+  socket: Socket;
+  /** WsTracker id, so the connection shows in the dev-admin /__dev/api/websockets list. */
+  trackerId?: string;
+}
+
+/**
+ * Connection manager for the dev-reload channel (`/__dev_reload`).
+ *
+ * Mirrors Python's `_ws_manager` scoped to `/__dev_reload`: it accepts the
+ * RFC 6455 handshake on the *main* dev server's HTTP `upgrade` event, holds the
+ * raw sockets open, and lets `POST /__dev/api/reload` push an instant reload to
+ * every connected browser via {@link broadcast}. The framework never reads from
+ * the client — the open socket is the whole point. This restores the documented
+ * WebSocket-primary DevReload design (the dev toolbar and dev-admin dashboard
+ * both connect here). Registered only when `TINA4_DEBUG` is on, and never on the
+ * stable AI port.
+ */
+class DevReloadWsManager {
+  private clients: Set<DevReloadClient> = new Set();
+  /** Optional hooks (add/remove) so the dev-admin connection list stays in sync. */
+  private onAdd?: (remoteAddress: string, path: string) => string;
+  private onRemove?: (id: string) => void;
+
+  /** Wire dev-admin tracking callbacks (WsTracker.add / WsTracker.remove). */
+  setTracker(onAdd: (remoteAddress: string, path: string) => string, onRemove: (id: string) => void): void {
+    this.onAdd = onAdd;
+    this.onRemove = onRemove;
+  }
+
+  /** Number of currently-open dev-reload sockets (test/diagnostic helper). */
+  get size(): number {
+    return this.clients.size;
+  }
+
+  /**
+   * Accept a WebSocket upgrade on `/__dev_reload` and hold the socket open.
+   *
+   * Completes the RFC 6455 handshake, registers the connection, and drains
+   * inbound frames — responding to pings and cleaning up on close — without
+   * ever interpreting client data. Returns true if the handshake was accepted.
+   */
+  handleUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): boolean {
+    const wsKey = req.headers["sec-websocket-key"];
+    if (!wsKey || (typeof wsKey === "string" && wsKey.length === 0)) {
+      try {
+        socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+        socket.destroy();
+      } catch {
+        /* socket already gone */
+      }
+      return false;
+    }
+
+    const acceptKey = computeAcceptKey(Array.isArray(wsKey) ? wsKey[0] : wsKey);
+    const response = [
+      "HTTP/1.1 101 Switching Protocols",
+      "Upgrade: websocket",
+      "Connection: Upgrade",
+      `Sec-WebSocket-Accept: ${acceptKey}`,
+      "",
+      "",
+    ].join("\r\n");
+    try {
+      socket.write(response);
+    } catch {
+      return false;
+    }
+
+    const client: DevReloadClient = { socket };
+    if (this.onAdd) {
+      client.trackerId = this.onAdd(socket.remoteAddress ?? "unknown", "/__dev_reload");
+    }
+    this.clients.add(client);
+
+    const cleanup = () => {
+      if (!this.clients.has(client)) return;
+      this.clients.delete(client);
+      if (client.trackerId && this.onRemove) this.onRemove(client.trackerId);
+    };
+
+    // We don't act on client data, but we must still drain frames so the OS
+    // buffer doesn't stall, answer pings, and notice a client-side close.
+    let buffer = head && head.length > 0 ? Buffer.from(head) : Buffer.alloc(0);
+    socket.on("data", (chunk: Buffer) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      while (buffer.length > 0) {
+        const frame = parseFrame(buffer);
+        if (!frame) break;
+        buffer = buffer.subarray(frame.bytesConsumed);
+        if (frame.opcode === OP_PING) {
+          try {
+            socket.write(buildFrame(OP_PONG, frame.payload));
+          } catch {
+            /* client disconnected */
+          }
+        } else if (frame.opcode === OP_CLOSE) {
+          try {
+            socket.write(buildFrame(OP_CLOSE, Buffer.from([0x03, 0xe8])));
+            socket.end();
+          } catch {
+            /* already closed */
+          }
+          cleanup();
+          return;
+        }
+      }
+    });
+    socket.on("close", cleanup);
+    socket.on("error", cleanup);
+    return true;
+  }
+
+  /**
+   * Broadcast a text frame to every connected dev-reload client.
+   *
+   * Best-effort: a dead socket is dropped silently. Never throws — the caller
+   * (`POST /__dev/api/reload`) must not 500 because a browser tab went away.
+   */
+  broadcast(message: string): void {
+    if (this.clients.size === 0) return;
+    const frame = buildFrame(OP_TEXT, Buffer.from(message, "utf-8"));
+    for (const client of Array.from(this.clients)) {
+      try {
+        client.socket.write(frame);
+      } catch {
+        this.clients.delete(client);
+        if (client.trackerId && this.onRemove) this.onRemove(client.trackerId);
+      }
+    }
+  }
+}
+
+/** Process-wide dev-reload manager (one channel: `/__dev_reload`). */
+export const devReloadWs = new DevReloadWsManager();