@zerotal/devtools 1.7.3 → 1.7.5

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/api-surface.md

@@ -47,8 +47,6 @@ class TraceStore = {
 
 const traceSink = TraceSink
 
-function _setTraceStore = (store: TraceStore | null) => void
-
 function attributeBindings = (sql: string, count: number) => Array<string | undefined>
 
 function DevtoolsConfig = (options?: Partial<DevtoolsConfigShape>) => DevtoolsConfigShape

package/package.json

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

package/src/DevtoolsInjectionMiddleware.ts

@@ -238,6 +238,44 @@ export class DevtoolsInjectionMiddleware extends BaseMiddleware<DevtoolsInjectio
       });
     }
 
-    return next();
+    // Nothing else under the prefix; fall through to the app and mark the page.
+    const response = await next();
+    return response instanceof Response ? await _markPage(http, response) : response;
   }
 }
+
+/**
+ * Tell the browser half that a server half exists, by injecting one `<meta>`.
+ *
+ * The client used to find out by asking — a `GET api/channels` on every page
+ * load, treating a 404 as "not here". That failed closed, which was the point,
+ * but it meant a production page fetched a URL that was *designed* to 404 and
+ * the browser logged it. A reviewer reading that console sees development
+ * tooling running on a live site; the honest reading of a deliberate 404 and a
+ * leaked debug endpoint look identical from the outside.
+ *
+ * Inverting it removes the request rather than hiding it. The provider is gated
+ * on the environment, so in production this middleware is not in the stack at
+ * all: no marker is written, the client finds none, and it makes **zero**
+ * requests instead of one per page load. It also saves the round trip in
+ * development, where the panel now mounts on the first frame rather than after
+ * a fetch resolves.
+ *
+ * Absence stays the safe default — an app served by something that never runs
+ * this middleware gets no panel, which is the same answer the probe gave.
+ */
+async function _markPage(http: HttpContext, response: Response): Promise<Response> {
+  const type = response.headers.get("content-type") ?? "";
+  if (!type.includes("text/html")) return response;
+
+  // Same gate as the endpoints: a marker on a page whose viewer could not use
+  // the endpoints anyway would only advertise that they are there.
+  if (!(await devtoolsAuthorized(http.request))) return response;
+
+  const html = await response.text();
+  const head = html.indexOf("</head>");
+  if (head === -1) return new Response(html, response);
+
+  const marker = `<meta name="zerotal-devtools" content="${DEVTOOLS_PREFIX}">`;
+  return new Response(html.slice(0, head) + marker + html.slice(head), response);
+}

package/src/client/index.ts

@@ -78,28 +78,113 @@ 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 unless there is a server half to mount against.
+    //
+    // 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 does, with a
+    // comment explaining why that is safe — is covered without knowing to be.
+    void serverPresent(base)
+      .then((present) => {
+        if (!present) return;
+        if (document.getElementById("__zerotal_dt__")) return;
+        mount();
+      })
+      // A panel that cannot build itself must not become an unhandled rejection
+      // in the host application's console — or, worse, in its error reporting.
+      // This is a development convenience failing; say so and leave the page it
+      // was decorating alone.
+      .catch((error: unknown) => {
+        console.warn("[Zerotal DevTools] could not start:", error);
+      });
   },
 };
 
+/**
+ * Whether the devtools routes exist on this origin.
+ *
+ * Two ways to know, and the order matters.
+ *
+ * **The marker.** `DevtoolsInjectionMiddleware` writes
+ * `<meta name="zerotal-devtools">` into the HTML it passes through, and it is
+ * only in the stack when the provider is active. When it is there, presence is
+ * already in the document: no request, and the panel mounts on the first frame.
+ *
+ * **The probe, on a development host only.** `Router.raw` bypasses the global
+ * middleware pipeline by design, so an app that serves its pages that way — the
+ * documentation site does — never receives the marker however active devtools is.
+ * Asking is the only way left for those, so the fetch survives, restricted to the
+ * hostnames a production site is never served from.
+ *
+ * That restriction is the point. The first version of this probed unconditionally
+ * and was correct — a 404 meant absent, and nothing mounted — but it left a
+ * request to a devtools URL in the console of every production page, which reads
+ * as leaked tooling no matter how deliberate it is. A real domain now makes no
+ * request at all, and the apps that need asking are the ones nobody else can see.
+ *
+ * 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> {
+  if (document.querySelector('meta[name="zerotal-devtools"]') !== null) return true;
+  if (!isDevelopmentHost(location.hostname)) return false;
+
+  try {
+    const res = await fetch(`${base}/api/channels`, {
+      method: "GET",
+      cache: "no-store",
+      headers: { accept: "application/json" },
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `hostname` is one a development server answers on.
+ *
+ * Loopback and the private ranges — the last of those so a panel still appears
+ * when a phone on the same network is pointed at a laptop's dev server, which is
+ * most of what anyone uses a second device for.
+ */
+function isDevelopmentHost(hostname: string): boolean {
+  if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]") return true;
+  if (hostname.endsWith(".localhost") || hostname.endsWith(".test")) return true;
+  // 10.0.0.0/8, 192.168.0.0/16, and 172.16.0.0/12.
+  return /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(hostname);
+}
+
 // ── Public surface ────────────────────────────────────────────────────────────
 //
 // The panel is markup, and markup is awkward to assert on. What is exported here