@zerotal/devtools 1.7.3 → 1.7.4

package/CHANGELOG.md

@@ -8,6 +8,22 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.7.4] — 2026-08-21
+
+### Fixed
+
+- **The panel no longer mounts when there is no server half to talk to.** The provider is
+  gated on the environment, so in production the devtools routes are absent — and the client
+  read that as permission to start anyway and "connect to nothing". It did not connect to
+  nothing: `DevTools.start()` mounted the panel first and discovered the absence afterwards,
+  so an app calling it unconditionally served a floating DevTools bar to every visitor, its
+  tabs reading `Could not read the map — HTTP 404`. zerotal.dev did exactly this.
+
+  `start()` now probes `api/channels` and mounts only if it answers. Nothing is constructed
+  before that resolves — no shell, no shadow root, no `EventSource`, no listeners. Any
+  failure (404, offline, CSP, a proxy answering HTML) is read as absent: a missed panel costs
+  a developer one keystroke, and a stray one is a debug surface on a production page.
+
 ## [1.7.1] — 2026-08-16
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/devtools",
-  "version": "1.7.3",
+  "version": "1.7.4",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,11 +31,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.3"
+    "@zerotal/core": "1.7.4"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.7.3"
+    "@zerotal/orm": "1.7.4"
   },
   "description": "In-browser developer tools for Zerotal — request traces, an inspector panel, and an extensible tab registry.",
   "keywords": [

package/src/client/index.ts

@@ -78,28 +78,74 @@ export const DevTools = {
     const base = (opts.endpoint ?? "/__zerotal/devtools").replace(/\/$/, "");
     const standalone = opts.mode === "standalone";
 
-    const store = new Store(standalone, base);
-    const transport = connect(base, store);
+    const mount = (): void => {
+      const store = new Store(standalone, base);
+      const transport = connect(base, store);
 
-    // What the browser measured for this page load, read once after it settles.
-    // The panel reports server duration as though it were the user's experience;
-    // it is not, and this is the only place that knows the difference.
-    onceLoaded(() => {
-      store.clientMetrics = collectClientMetrics();
-      store.changed();
-    });
+      // What the browser measured for this page load, read once after it settles.
+      // The panel reports server duration as though it were the user's experience;
+      // it is not, and this is the only place that knows the difference.
+      onceLoaded(() => {
+        store.clientMetrics = collectClientMetrics();
+        store.changed();
+      });
+
+      mountShell({
+        base,
+        standalone,
+        mount: opts.mount ?? document.body,
+        store,
+        transport,
+        tabs: BUILT_IN,
+      });
+    };
 
-    mountShell({
-      base,
-      standalone,
-      mount: opts.mount ?? document.body,
-      store,
-      transport,
-      tabs: BUILT_IN,
+    // Mount nothing until the server half answers.
+    //
+    // The provider is gated on the environment, so in production the endpoints are
+    // absent — and the client took that to mean it could start anyway and simply
+    // connect to nothing. It could not: `mountShell` pinned the panel to the page
+    // regardless, so zerotal.dev served a floating DevTools bar to every visitor,
+    // opening onto tabs reading `Could not read the map — HTTP 404` because the
+    // routes behind them do not exist in production.
+    //
+    // Failing closed here rather than in each app's entry file is deliberate: an
+    // app that calls `start()` unconditionally — which the docs site did, with a
+    // comment explaining why that was safe — is covered without knowing to be.
+    void serverPresent(base).then((present) => {
+      if (!present) return;
+      if (document.getElementById("__zerotal_dt__")) return;
+      mount();
     });
   },
 };
 
+/**
+ * Whether the devtools routes exist on this origin.
+ *
+ * `api/channels` rather than `sse`: it answers and closes, where the stream stays
+ * open and would leave a connection hanging on every page load just to discover
+ * the panel should not be there. `no-store` so a 404 is not cached into a session
+ * that later starts a dev server on the same origin.
+ *
+ * Any failure — offline, blocked by CSP, a proxy returning HTML — is treated as
+ * absent. The panel is a development convenience, and the cost of guessing wrong
+ * is that a developer presses Alt+D twice; the cost of guessing wrong the other
+ * way is a debug surface on a production page.
+ */
+async function serverPresent(base: string): Promise<boolean> {
+  try {
+    const res = await fetch(`${base}/api/channels`, {
+      method: "GET",
+      cache: "no-store",
+      headers: { accept: "application/json" },
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
 // ── Public surface ────────────────────────────────────────────────────────────
 //
 // The panel is markup, and markup is awkward to assert on. What is exported here