@zerotal/devtools 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -8,6 +8,50 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-08-29
+
+### Documented
+
+- **Every promised export is documented.** The `docs-coverage` gate reads `maturity: stable` as a
+  promise about a package's exports, and measures how much of that promise is written down. It
+  was 798 gaps across the suite; it is now zero. This package's share is covered on its own
+  pages — types named, options shapes described, and the decisions behind them recorded where
+  somebody looking for them will find them.
+
+## [1.8.1] — 2026-08-26
+
+### Fixed
+
+- **A page keeps the panel while its own assets load.** Opening `/login` selected `/login`,
+  then `/favicon.ico` a few milliseconds later, then `/css/app.css`: live mode selected every
+  trace as it arrived, and a page's sub-resources arrive right behind it. The bar named a
+  request nobody asked about, the detail below described that request's headers and its empty
+  session, and the page under inspection had scrolled into the list. Nothing shown was wrong;
+  it was all about the wrong request.
+
+  Traces are classified into three kinds rather than two, because "not the document" would
+  have suppressed the form post and the Inertia visit — the requests most worth watching.
+  What is skipped over is narrower: a sub-resource the browser fetched on its own initiative.
+  The browser is asked rather than the URL, since an app may serve an API from a `.js` route
+  and a build that hashes its asset names has no extension to read; response content type is
+  the fallback, so a page fetched by curl still reads as a page. Anything unclassifiable is
+  `api`, never `asset`. An asset still takes the selection when nothing is selected, so a
+  panel opened mid-load shows a request rather than an empty pane, and a paused panel still
+  counts assets toward its pending badge.
+
+### Added
+
+- **A `kind` facet on the All tab**, beside method and status. Assets were never the problem,
+  only their claim on the selection, so they are not hidden: pick `page` and `api` for a list
+  without fifty stylesheet fetches in it, or `asset` alone for what the browser pulled in,
+  what it cost and which of it 404'd — which was not visible anywhere before. `Facets.kinds`
+  is optional, because that interface is exported from `@zerotal/devtools/client` and a
+  required field added to a published interface breaks whoever builds one by hand.
+
+- **`sec-fetch-dest` and `sec-fetch-mode` are recorded**, joining the safe header list. They
+  are where the classification above comes from, and they state what a request was for
+  without saying anything about who made it.
+
 ## [1.7.4] — 2026-08-21
 
 ### Fixed

package/api-surface.md

@@ -45,10 +45,6 @@ class TraceStore = {
   subscribe: (fn: Subscriber) => () => void
 }
 
-const traceSink = TraceSink
-
-function attributeBindings = (sql: string, count: number) => Array<string | undefined>
-
 function DevtoolsConfig = (options?: Partial<DevtoolsConfigShape>) => DevtoolsConfigShape
 
 function devtoolsEnabled = () => boolean
@@ -61,10 +57,6 @@ function redactCacheKey = (key: string, options?: RedactionOptions) => string
 
 function redactValue = (value: unknown, options?: RedactionOptions) => unknown
 
-function startDevtoolsStream = () => () => void
-
-function traceChannels = () => TraceChannelDescriptor[]
-
 function traceStore = () => TraceStore
 
 interface AuthInfo = {
@@ -94,8 +86,6 @@ interface DevtoolsConfigShape = {
   redact: RedactionOptions
 }
 
-interface DevtoolsInjectionOptions = {}
-
 interface DevtoolsPanelPlugin = {
   badge?: () => number | string | undefined
   id: string
@@ -276,6 +266,7 @@ interface DevtoolsPanelPlugin = {
 
 interface Facets = {
   errors: boolean
+  kinds?: RequestKind[]
   methods: string[]
   nPlusOne: boolean
   slow: boolean

package/package.json

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

package/src/DevtoolsInjectionMiddleware.ts

@@ -43,6 +43,7 @@ async function _buildDashboardJs(): Promise<string> {
   return _dashboardJs;
 }
 
+/** @internal */
 export interface DevtoolsInjectionOptions {
   // reserved for future use
 }
@@ -102,6 +103,8 @@ const SSE_HEARTBEAT_MS = 25_000;
  * built the one the app's config asks for.
  *
  * @returns A disposer that unsubscribes and closes connected clients.
+ *
+ * @internal
  */
 export function startDevtoolsStream(): () => void {
   const unsubscribe = traceStore().subscribe((trace) => {

package/src/client/filter.ts

@@ -11,6 +11,7 @@
  * browser.
  */
 import type { RequestTrace } from "../RequestTrace.ts";
+import { requestKind, type RequestKind } from "./kind.ts";
 
 /**
  * A request slower than this reads as slow.
@@ -33,16 +34,37 @@ export interface Facets {
   slow: boolean;
   /** Only requests with an N+1 warning. */
   nPlusOne: boolean;
+  /**
+   * Request kinds to show. Empty means every kind.
+   *
+   * The one facet whose usual job is *subtraction*: an app's own traffic is
+   * `document` and `api`, and picking those two is how you get a list without
+   * fifty stylesheet fetches in it. Picking `asset` alone is the other half —
+   * what the browser pulled in, what it cost, and which of it 404'd, which is
+   * not visible anywhere else.
+   *
+   * Optional because {@link Facets} is exported from `@zerotal/devtools/client`
+   * and a required field added to a published interface breaks whoever builds one
+   * by hand. `noFacets()` always sets it; reads here tolerate its absence.
+   */
+  kinds?: RequestKind[];
 }
 
 /** No narrowing at all — what a fresh panel starts with. */
 export function noFacets(): Facets {
-  return { methods: [], statusClasses: [], errors: false, slow: false, nPlusOne: false };
+  return { methods: [], statusClasses: [], errors: false, slow: false, nPlusOne: false, kinds: [] };
 }
 
 /** Whether any facet is actually narrowing, for the "clear" affordance. */
 export function facetsActive(f: Facets): boolean {
-  return f.methods.length > 0 || f.statusClasses.length > 0 || f.errors || f.slow || f.nPlusOne;
+  return (
+    f.methods.length > 0 ||
+    f.statusClasses.length > 0 ||
+    (f.kinds?.length ?? 0) > 0 ||
+    f.errors ||
+    f.slow ||
+    f.nPlusOne
+  );
 }
 
 /**
@@ -88,6 +110,7 @@ export function matchesFacets(trace: RequestTrace, f: Facets): boolean {
   if (f.errors && !trace.exception && trace.statusCode < 400) return false;
   if (f.slow && trace.durationMs <= SLOW_MS) return false;
   if (f.nPlusOne && !trace.warnings.length) return false;
+  if (f.kinds?.length && !f.kinds.includes(requestKind(trace))) return false;
   return true;
 }
 

package/src/client/kind.ts

@@ -0,0 +1,138 @@
+/**
+ * What kind of request a trace is — the page, the app talking, or a file the
+ * browser fetched because the page said to.
+ *
+ * The panel had no such notion, and one behaviour made that expensive: live mode
+ * selects every trace as it arrives, so opening `/login` selected `/login` for a
+ * few milliseconds and then `/favicon.ico`, `/css/app.css`, and whatever else the
+ * page pulled. The bar named a request nobody asked about, the detail below it
+ * described that request's headers and its empty session, and the page you were
+ * actually looking at had scrolled into the list. The information was never
+ * wrong; it was about the wrong thing.
+ *
+ * Three kinds, because two would not do the job. Suppressing "not the document"
+ * would suppress the form post and the Inertia visit — the requests most worth
+ * watching. What deserves to be skipped over is narrower than that: a
+ * sub-resource the browser fetched on its own initiative.
+ *
+ * ## Why the browser is asked rather than the URL
+ *
+ * `Sec-Fetch-Dest` is the purpose-built answer — the browser states what it
+ * wanted the response for, and it is the only source here that cannot be fooled.
+ * A `.js` path can serve an API, a route with no extension can serve a
+ * stylesheet, and an app that hashes its asset names has neither. The extension
+ * rule is last and exists for the clients that send no such header at all.
+ */
+import type { RequestTrace } from "../RequestTrace.ts";
+
+/**
+ * - `document` — a navigation. The page in the address bar.
+ * - `api` — the app talking: form posts, Inertia visits, fetch, anything a
+ *   script asked for on purpose.
+ * - `asset` — a sub-resource the browser fetched by itself.
+ */
+export type RequestKind = "document" | "api" | "asset";
+
+/** `Sec-Fetch-Dest` values that mean the browser wanted a file, not an answer. */
+const ASSET_DESTINATIONS = new Set([
+  "image",
+  "style",
+  "script",
+  "font",
+  "manifest",
+  "audio",
+  "video",
+  "track",
+  "embed",
+  "object",
+  "worker",
+  "sharedworker",
+  "serviceworker",
+  "paintworklet",
+  "audioworklet",
+  "xslt",
+  "report",
+]);
+
+/** Content types served as files. Checked as prefixes — parameters follow. */
+const ASSET_TYPES = [
+  "text/css",
+  "image/",
+  "font/",
+  "audio/",
+  "video/",
+  "application/javascript",
+  "text/javascript",
+  "application/font",
+  "application/manifest",
+];
+
+/** The last resort, for a client that announces nothing about itself. */
+const ASSET_EXTENSIONS = new Set([
+  "css",
+  "js",
+  "mjs",
+  "map",
+  "ico",
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "svg",
+  "webp",
+  "avif",
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "eot",
+  "mp3",
+  "mp4",
+  "webm",
+  "wasm",
+  "webmanifest",
+]);
+
+/** Case-insensitive header read — a trace's headers are whatever the client sent. */
+function header(trace: RequestTrace, name: string): string {
+  const headers = trace.headers ?? {};
+  const hit = Object.keys(headers).find((k) => k.toLowerCase() === name);
+  return hit ? String(headers[hit] ?? "").toLowerCase() : "";
+}
+
+function responseType(trace: RequestTrace): string {
+  const headers = trace.responseHeaders ?? {};
+  const hit = Object.keys(headers).find((k) => k.toLowerCase() === "content-type");
+  return hit ? String(headers[hit] ?? "").toLowerCase() : "";
+}
+
+/** Classify one trace. Never throws, and never guesses `asset` without a reason. */
+export function requestKind(trace: RequestTrace): RequestKind {
+  // 1. What the browser says it wanted the response for. Unfoolable, and absent
+  //    only from clients that are not browsers.
+  const dest = header(trace, "sec-fetch-dest");
+  if (dest === "document" || dest === "iframe" || dest === "frame") return "document";
+  if (ASSET_DESTINATIONS.has(dest)) return "asset";
+  if (dest === "empty") return "api";
+
+  // 2. What was actually served. A page is a page whatever asked for it, which
+  //    is what makes this right for curl and for a server-rendered form post.
+  const type = responseType(trace);
+  if (type.startsWith("text/html")) return "document";
+  if (ASSET_TYPES.some((prefix) => type.startsWith(prefix))) return "asset";
+
+  // 3. The path, for a client that announced nothing and a response that carried
+  //    no type — a 404 for a missing stylesheet, most often.
+  const extension = (trace.path ?? "").split("?")[0]?.split(".").pop()?.toLowerCase() ?? "";
+  if (extension && ASSET_EXTENSIONS.has(extension)) return "asset";
+
+  // Unclassifiable is `api`, never `asset`. Being wrong here decides whether a
+  // request is skipped over, and skipping the wrong one is how the panel stops
+  // showing you what you came to see.
+  return "api";
+}
+
+/** Whether live mode should move the selection onto this trace. */
+export function worthSelecting(trace: RequestTrace): boolean {
+  return requestKind(trace) !== "asset";
+}

package/src/client/state.ts

@@ -11,6 +11,7 @@ import type { RequestTrace, TraceChannelDescriptor } from "../RequestTrace.ts";
 import type { EditorName } from "../editor.ts";
 import type { ClientMetric } from "./metrics.ts";
 import { noFacets, traceMatches, type Facets } from "./filter.ts";
+import { worthSelecting } from "./kind.ts";
 import type { ThemeChoice } from "./ui/theme.ts";
 
 /**
@@ -335,11 +336,28 @@ export class Store {
   addTrace(trace: RequestTrace): void {
     this.traces.unshift(trace);
     if (this.traces.length > this.capacity) this.traces.length = this.capacity;
-    if (this.live) this.selected = trace;
-    else this.pending++;
+    if (this.live && this._takesSelection(trace)) this.selected = trace;
+    else if (!this.live) this.pending++;
     this.changed();
   }
 
+  /**
+   * Whether a newly arrived trace should become the selection in live mode.
+   *
+   * Everything did, which meant a page selected itself and was then replaced by
+   * its own favicon a few milliseconds later. The bar named a request nobody
+   * asked about while the page you were looking at scrolled into the list.
+   *
+   * A sub-resource yields to whatever is selected — but only to something. With
+   * nothing selected an asset is still better than an empty panel, and a page
+   * whose document 304s while its assets do not would otherwise show nothing at
+   * all.
+   */
+  private _takesSelection(trace: RequestTrace): boolean {
+    if (worthSelecting(trace)) return true;
+    return this.selected === null || !worthSelecting(this.selected);
+  }
+
   clear(): void {
     this.traces = [];
     this.selected = null;

package/src/client/tabs/all.ts

@@ -8,6 +8,7 @@
  */
 import { facetsActive, methodsPresent, noFacets, type Facets } from "../filter.ts";
 import { foldTraceRows, type TraceRow } from "../tree.ts";
+import type { RequestKind } from "../kind.ts";
 import { dCls, esc, fmt, scCls } from "../ui/format.ts";
 import { el, reconcile } from "../ui/render.ts";
 import type { TabContext, TabView } from "./types.ts";
@@ -36,6 +37,16 @@ const STATUS_CLASSES: Array<[string, string]> = [
   ["5", "5xx"],
 ];
 
+/**
+ * Labelled for what they are from the reader's side rather than by their code
+ * name: "page" is what someone is looking at, "asset" is what came with it.
+ */
+const KIND_CHIPS: Array<[RequestKind, string]> = [
+  ["document", "page"],
+  ["api", "api"],
+  ["asset", "asset"],
+];
+
 // ── Skeleton ──────────────────────────────────────────────────────────────────
 //
 // Built once per visit to the tab and then only updated. The filter input in
@@ -82,11 +93,17 @@ function facetChips(store: TabContext["store"]): string {
     chip("status", digit, label, f.statusClasses.includes(digit)),
   ).join("");
 
+  const kinds = KIND_CHIPS.map(([kind, label]) =>
+    chip("kind", kind, label, f.kinds?.includes(kind) ?? false),
+  ).join("");
+
   return (
     methods +
     (methods ? `<span class="fsep"></span>` : "") +
     statuses +
     `<span class="fsep"></span>` +
+    kinds +
+    `<span class="fsep"></span>` +
     chip("errors", "", "errors", f.errors, true) +
     chip("slow", "", "slow", f.slow, true) +
     chip("nplus", "", "n+1", f.nPlusOne, true) +
@@ -103,6 +120,8 @@ export function toggleFacet(f: Facets, kind: string, value: string): Facets {
       return { ...f, methods: drop(f.methods, value) };
     case "status":
       return { ...f, statusClasses: drop(f.statusClasses, value) };
+    case "kind":
+      return { ...f, kinds: drop(f.kinds ?? [], value as RequestKind) };
     case "errors":
       return { ...f, errors: !f.errors };
     case "slow":

package/src/redaction.ts

@@ -247,6 +247,8 @@ export function redactBindings(
  * `SET col = ?`, and `WHERE col <op> ?` (including `IN (?, ?)`, where every
  * placeholder belongs to the same column). Returns `undefined` at any position it
  * cannot attribute.
+ *
+ * @internal
  */
 export function attributeBindings(sql: string, count: number): Array<string | undefined> {
   const out: Array<string | undefined> = new Array(count).fill(undefined);

package/src/tracing.ts

@@ -99,6 +99,8 @@ const _channels = new Map<string, TraceChannelDescriptor>();
  *
  * A `hidden` channel is left out: its entries are still recorded and still reach
  * the panel on the trace, but whatever renders them is not this generic row list.
+ *
+ * @internal
  */
 export function traceChannels(): TraceChannelDescriptor[] {
   return [...(_channels.values() as Iterable<TraceChannelDescriptor>)]
@@ -199,6 +201,7 @@ export interface TraceSink {
 // nothing: by the time a panel draws a row, the unredacted copy has already been
 // streamed to the browser and written to `.zerotal/devtools.sqlite`, where it
 // sits for a day. The sink is the last point where "not recorded" is still true.
+/** @internal */
 export const traceSink: TraceSink = {
   channel(descriptor: TraceChannelDescriptor): void {
     _channels.set(descriptor.id, descriptor);
@@ -261,6 +264,11 @@ function _cleanupBuffers(ctx: object): void {
  */
 const SAFE_HEADERS = new Set([
   "accept",
+  // What the browser wanted the response for — `document`, `image`, `style`.
+  // The only unfoolable way to tell a page from a file the page pulled in, and
+  // devtools classifies every trace by it.
+  "sec-fetch-dest",
+  "sec-fetch-mode",
   "content-type",
   "content-length",
   "user-agent",