npm - @zerotal/devtools - Versions diffs - 1.7.0 → 1.7.3 - Mend

@zerotal/devtools 1.7.0 → 1.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/CHANGELOG.md +97 -0
package/api-surface.md +4 -2
package/package.json +3 -3
package/src/RequestTrace.ts +10 -0
package/src/client/index.ts +13 -8
package/src/client/registry.ts +24 -2
package/src/client/state.ts +42 -3
package/src/client/tabs/all.ts +61 -14
package/src/client/tabs/app.ts +1 -0
package/src/client/tabs/cache.ts +1 -0
package/src/client/tabs/channel.ts +5 -4
package/src/client/tabs/exceptions.ts +1 -0
package/src/client/tabs/jobs.ts +1 -0
package/src/client/tabs/live.ts +66 -0
package/src/client/tabs/logs.ts +1 -0
package/src/client/tabs/mail.ts +1 -0
package/src/client/tabs/queries.ts +1 -0
package/src/client/tabs/request.ts +7 -8
package/src/client/tabs/sections.ts +115 -0
package/src/client/tabs/timeline.ts +1 -0
package/src/client/tabs/types.ts +17 -0
package/src/client/ui/format.ts +21 -2
package/src/client/ui/shell.ts +59 -10
package/src/client/ui/theme.ts +60 -4
package/src/tracing.ts +49 -6

package/CHANGELOG.md CHANGED Viewed

@@ -6,6 +6,103 @@ follows the Zerotal monorepo's unified versioning.
 **Maturity: `stable`**
+## [Unreleased]
+## [1.7.1] — 2026-08-16
+### Changed
+- **A request is a place, not twelve tabs.** The Requests strip carried fourteen tabs, twelve
+  of which described a single request — Queries, Timeline, Logs, Request, Exception, Mail,
+  Cache, Jobs, and every channel. They were empty for most requests, they answered a question
+  you can only ask about a request you have already picked, and under about 1100px they
+  scrolled off the right edge with nothing to say they had.
+  Every view now declares a `scope`. A request-scoped one is drawn inside whichever request
+  you are reading, as that request's own small strip of tabs; a session-scoped one keeps its
+  place in the panel's strip, because it keeps reading as you move between requests. Nothing
+  is reimplemented — a `TabView` was already "draw this trace into this element", which is
+  exactly what a section is.
+  Only the views with something to say appear, so the strip doubles as the summary: a request
+  showing Queries, Logs and Exception has told you what happened before you click anything. A
+  view that counts nothing is skipped before it renders, and anything that comes back as its
+  own empty-state line is dropped after.
+  Requests is now **Live**, **All** and whatever plugins are installed. App is untouched —
+  Routes, Config, Container, Providers, Events and Commands describe the app rather than a
+  request, which is exactly why they are tabs.
+- **A Live view, first and default.** The newest request, already open. Opening the panel now
+  shows the page you are looking at instead of a heading you navigate away from, and it
+  follows: click something and it is showing what just happened. It ignores pinning on
+  purpose — pinning is how you hold still and read something older.
+- **A request states its identity once.** The Request view opened with the method, path and
+  status — right for a tab that had to say which request it was describing, pure repetition
+  for a section sitting directly under the row that just said it, where it read as a second
+  heading competing with the real one.
+- **Clear sits with the list it clears.** A labelled button beside the filter, rather than
+  only the icon at the far end of the status bar.
+### Fixed
+- **Durations printed their whole float.** `fmt()` interpolated the number raw, so anything
+  measured with `performance.now()` — every Flow action, in the always-visible status bar —
+  read `3.6370999999926426ms`, while anything a caller had already rounded read `0ms` for a
+  query that plainly took time. Precision now follows magnitude: `0.42ms`, `3.6ms`, `143ms`,
+  `1.4s`. Numeric cells also use tabular figures, which is what made the request list's
+  right-aligned column ragged.
+- **Timeline legend swatches floated away from their labels.** The legend reuses `.tmark` for
+  its colour, and `.tmark` is absolutely positioned for the waterfall — so in the legend,
+  whose rows are not positioned, all seven squares escaped to the nearest positioned ancestor
+  and stacked above their own text.
+- **The panel covered the bottom of the page.** It is fixed to the viewport and reserved no
+  space, so the last strip of any page — 32px collapsed, the panel's full height open — could
+  not be scrolled to. The host page now gets matching bottom padding, updated on toggle and
+  resize, and `--zt-dt-height` is published on `<html>` for an app that would rather move
+  something of its own.
+- **Muted text failed WCAG AA, and focus was invisible.** `--muted` sat at 2.35:1 on the tab
+  strip — below AA for text of any size, and this is 10–11px text. It now measures 4.69:1 on
+  the strip and 5.50:1 on the status bar in dark, 5.38:1 in light. `:focus-visible` was
+  suppressed panel-wide, leaving keyboard navigation with no indicator at all; focusable
+  controls now draw a ring.
+### Added
+- **A contributed panel can read the selected trace.** `DevtoolsPanelPlugin.render` now
+  receives a second `context` argument carrying the trace selected in the request list. A
+  plugin exists because it owns live browser state, but the same events usually have a
+  server half recorded against a trace, and a plugin that could not reach it had to either
+  measure again client-side or show half the story in a tab of its own. `@zerotal/flow`'s
+  time-travel frames now print what each action cost on the server. The argument is
+  optional, so a plugin written against the one-argument form is untouched.
+- **`hidden` on a channel descriptor.** Records the entries on the trace but gives them no
+  tab, for a package that renders the data somewhere better than a generic row list. Flow
+  declares its actions this way now that its own panel prints them on the frame they belong
+  to.
+- **`TraceSink.finalise` — a trace for work that never was an HTTP request.** The sink let
+  a package buffer against a context but gave it no way to say that context was finished,
+  and a trace was only ever built from core's `RequestHandled` / `RequestFailed`. Anything
+  running against its own context outside the HTTP lifecycle therefore buffered its
+  evidence and dropped it: a Flow action over the WebSocket, and by the same mechanism a
+  queue job or a scheduled task.
+  `finalise(ctx, { startMs, durationMs, method })` builds the trace and pushes it. `method`
+  labels a synthetic request in the list — `@zerotal/flow` passes `FLOW`, which gets its own
+  colour so an action does not read as a second `GET` of the page it ran on. Finalising is
+  once per context, whichever claims it first, so a context that finalises itself can never
+  push a duplicate carrying none of the evidence.
+  Found by wiring DevTools into this repo's own `apps/docs`: the Flow tab could only ever
+  report "No flow activity during this request".
 ## [1.7.0] — 2026-08-16
 ### Added

package/api-surface.md CHANGED Viewed

@@ -101,7 +101,7 @@ interface DevtoolsInjectionOptions = {}
 interface DevtoolsPanelPlugin = {
   badge?: () => number | string | undefined
   id: string
-  render: (el: HTMLElement) => void
+  render: (el: HTMLElement, context?: DevtoolsPanelContext) => void
   title: string
 }
@@ -200,6 +200,7 @@ interface TraceChannelDescriptor = {
   badge?: string
   flags?: string[]
   groupBy?: string
+  hidden?: boolean
   id: string
   label: string
   meta?: string[]
@@ -224,6 +225,7 @@ interface TraceSink = {
   bufferQuery: (ctx: object, q: QuerySpan) => void
   bufferWarning: (ctx: object, w: NPlusOneWarning) => void
   channel: (descriptor: TraceChannelDescriptor) => void
+  finalise: (ctx: object, meta: {    startMs: number;    durationMs: number;    method?: string;}) => void
   record: (ctx: object, channel: string, entry: Record<string, unknown>) => void
 }
@@ -270,7 +272,7 @@ interface DevtoolsClientOptions = {
 interface DevtoolsPanelPlugin = {
   badge?: () => number | string | undefined
   id: string
-  render: (el: HTMLElement) => void
+  render: (el: HTMLElement, context?: DevtoolsPanelContext) => void
   title: string
 }

package/package.json CHANGED Viewed

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

package/src/RequestTrace.ts CHANGED Viewed

@@ -141,6 +141,16 @@ export interface TraceChannelDescriptor {
   warn?: string;
   /** Sort order among channel tabs. Lower sorts first. Defaults to 100. */
   order?: number;
+  /**
+   * Record the entries on the trace but give them no tab of their own.
+   *
+   * For a package that renders this data somewhere better than a generic row
+   * list — its own plugin panel, say — while still wanting it on the persisted
+   * trace. Flow declares its actions this way: the numbers belong on the trace,
+   * but they read as one line on a time-travel frame rather than as a tab
+   * repeating what the trace header already says.
+   */
+  hidden?: boolean;
   // ── Presentation hints ──────────────────────────────────────────────────────
   //

package/src/client/index.ts CHANGED Viewed

@@ -21,6 +21,7 @@ import { collectClientMetrics, onceLoaded } from "./metrics.ts";
 import { connect } from "./transport.ts";
 import { mountShell } from "./ui/shell.ts";
 import { allTab } from "./tabs/all.ts";
+import { liveTab } from "./tabs/live.ts";
 import { cacheTab } from "./tabs/cache.ts";
 import { exceptionsTab } from "./tabs/exceptions.ts";
 import { jobsTab } from "./tabs/jobs.ts";
@@ -47,22 +48,26 @@ export interface DevtoolsClientOptions {
 }
 /**
- * The built-in tabs, in strip order.
+ * The built-in views, in strip order.
  *
- * The order is also the `1`–`9` keyboard order, so it is worth being deliberate
- * about: queries first because it is where a request explains itself, all last
- * because it is where you go to leave the request you are on.
+ * Only two of these are tabs. The rest are `scope: "request"` — sections of
+ * whichever request you are reading, in this order, rather than headings in a
+ * strip that are empty until you have picked something. Request leads because it
+ * says what the thing *was*; the exception comes next because if there is one it
+ * is why you opened the panel; then the work it did, and the waterfall last,
+ * being the summary of everything above it.
  */
 const BUILT_IN = [
-  queriesTab,
-  timelineTab,
-  logsTab,
+  liveTab,
+  allTab,
   requestTab,
   exceptionsTab,
+  queriesTab,
+  logsTab,
   mailTab,
   cacheTab,
   jobsTab,
-  allTab,
+  timelineTab,
 ];
 export const DevTools = {

package/src/client/registry.ts CHANGED Viewed

@@ -12,6 +12,23 @@
  * has a shipped consumer, so it survived the client rewrite unchanged.
  */
+import type { RequestTrace } from "../RequestTrace.ts";
+/**
+ * What the panel knows when it asks a plugin to draw.
+ *
+ * A plugin owns live browser state, which is why it renders itself rather than
+ * declaring a channel. But the same events usually have a server half recorded
+ * against a trace, and a plugin that cannot reach it has to either duplicate the
+ * measurement client-side or show half the story in a tab of its own. Flow's
+ * time-travel frames and its server actions are the case in point: the same
+ * clicks, once from each end.
+ */
+export interface DevtoolsPanelContext {
+  /** The trace selected in the request list, or `null` when none is. */
+  trace: RequestTrace | null;
+}
 /** A panel another package contributes as a tab in the Zerotal devtools. */
 export interface DevtoolsPanelPlugin {
   /** Unique id — the tab is addressed internally as `plugin:<id>`. */
@@ -20,8 +37,13 @@ export interface DevtoolsPanelPlugin {
   title: string;
   /** Optional badge value (e.g. a count); a falsy return hides the badge. */
   badge?: () => number | string | undefined;
-  /** Render the panel's content into `el` (the shared, persistent content area). */
-  render: (el: HTMLElement) => void;
+  /**
+   * Render the panel's content into `el` (the shared, persistent content area).
+   *
+   * `context` is optional so a plugin written against the one-argument form keeps
+   * working untouched — it simply ignores an argument it never declared.
+   */
+  render: (el: HTMLElement, context?: DevtoolsPanelContext) => void;
 }
 export interface DevtoolsRegistry {

package/src/client/state.ts CHANGED Viewed

@@ -38,6 +38,8 @@ export interface PersistedUi {
   section: Section;
   tab: string;
   appTab: string;
+  /** The view showing inside an open request. */
+  sectionTab: string;
   filter: string;
   facets: Facets;
   height: number;
@@ -85,6 +87,17 @@ export class Store {
   traces: RequestTrace[] = [];
   channels: TraceChannelDescriptor[] = [];
   selected: RequestTrace | null = null;
+  /** The request whose detail is open in the list, by trace id. */
+  openTraceId: string | null = null;
+  /**
+   * Which view is showing inside the request you are reading.
+   *
+   * Kept across requests on purpose: someone comparing the queries of one
+   * request against the next wants the queries again, not to be returned to the
+   * top every time. Falls back to the first available when a request has nothing
+   * to show under it.
+   */
+  sectionTab = "";
   connected = false;
   /**
    * How many traces to keep. Replaced by the server's real capacity when the
@@ -145,8 +158,13 @@ export class Store {
     const saved = loadUi();
     this.open = standalone || saved.open === true;
     this.section = saved.section === "app" ? "app" : "requests";
-    this.tab = saved.tab ?? "queries";
+    // Live by default: the panel opens on the request you are looking at rather
+    // than on a heading you then have to navigate away from. `queries` is no
+    // longer a tab at all — a persisted one from before this change falls back to
+    // the first, which is Live.
+    this.tab = saved.tab === "queries" ? "live" : (saved.tab ?? "live");
     this.appTab = saved.appTab ?? "app:routes";
+    this.sectionTab = saved.sectionTab ?? "";
     this.filter = saved.filter ?? "";
     this.facets = { ...noFacets(), ...(saved.facets ?? {}) };
     this.height = Math.max(MIN_HEIGHT, saved.height ?? DEFAULT_HEIGHT);
@@ -171,6 +189,7 @@ export class Store {
       section: this.section,
       appTab: this.appTab,
       tab: this.tab,
+      sectionTab: this.sectionTab,
       filter: this.filter,
       facets: this.facets,
       height: this.height,
@@ -202,6 +221,14 @@ export class Store {
     return this.section === "app" ? this.appTab : this.tab;
   }
+  /** Pick the view showing inside the open request. */
+  setSectionTab(id: string): void {
+    if (this.sectionTab === id) return;
+    this.sectionTab = id;
+    this.persist();
+    this.changed();
+  }
   setTab(tab: string): void {
     const key = this.section === "app" ? "appTab" : "tab";
     if (this[key] === tab) return;
@@ -248,15 +275,27 @@ export class Store {
   }
   /** Pin a trace and stop following the newest. */
-  select(trace: RequestTrace | null, { switchTab = false } = {}): void {
+  select(trace: RequestTrace | null): void {
     this.selected = trace;
     this.live = false;
     this.pending = 0;
-    if (switchTab && this.tab === "all") this.tab = "queries";
     this.persist();
     this.changed();
   }
+  /**
+   * Open a request's detail in the list, or close it if it is already open.
+   *
+   * Opening pins as well, because the detail and the status bar have to agree
+   * about which request you are reading. One at a time: the detail is tall, and
+   * two open at once is a list you cannot scan.
+   */
+  toggleOpen(trace: RequestTrace | null): void {
+    if (!trace) return;
+    this.openTraceId = this.openTraceId === trace.id ? null : trace.id;
+    this.select(trace);
+  }
   /** Follow the newest request again, clearing the backlog offer. */
   follow(): void {
     this.live = true;

package/src/client/tabs/all.ts CHANGED Viewed

@@ -11,6 +11,8 @@ import { foldTraceRows, type TraceRow } from "../tree.ts";
 import { dCls, esc, fmt, scCls } from "../ui/format.ts";
 import { el, reconcile } from "../ui/render.ts";
 import type { TabContext, TabView } from "./types.ts";
+import type { RequestTrace } from "../../RequestTrace.ts";
+import { renderSections } from "./sections.ts";
 /**
  * Row height in pixels, which the stylesheet pins.
@@ -47,6 +49,10 @@ function skeleton(): string {
     `<input id="filter" class="finput" type="search" ` +
     `placeholder="Filter by path, method, status, or controller…">` +
     `<span class="dim" id="fcount"></span>` +
+    // Labelled rather than the bar's icon: this is where you are when you decide
+    // the history is in your way, and the icon at the far end of the status bar
+    // is not where you look for it.
+    `<button class="tbtn" data-action="clear" title="Discard every recorded request">Clear</button>` +
     `</div>` +
     `<div class="facets" id="facets"></div>` +
     `<div id="rowswrap">` +
@@ -117,7 +123,14 @@ function rowKey(r: TraceRow): string {
   return `${r.trace.id}:${r.child ? "c" : "h"}`;
 }
-function rowHtml(r: TraceRow, selectedId: string | undefined): string {
+/** What the list draws: request rows, and the detail of whichever one is open. */
+type DrawItem = { kind: "row"; row: TraceRow } | { kind: "detail"; trace: RequestTrace };
+function itemKey(item: DrawItem): string {
+  return item.kind === "detail" ? `${item.trace.id}:d` : rowKey(item.row);
+}
+function rowHtml(r: TraceRow, selectedId: string | undefined, openId: string | null): string {
   const t = r.trace;
   const toggle = r.groupKey
     ? `<button class="gtog" data-group="${esc(r.groupKey)}" title="Requests in this batch">` +
@@ -126,6 +139,7 @@ function rowHtml(r: TraceRow, selectedId: string | undefined): string {
   return (
     `<div class="hrow${t.id === selectedId ? " cur" : ""}${t.exception ? " err" : ""}` +
     `${r.child ? " child" : ""}" data-idx="${r.index}">` +
+    `<span class="hchev">${t.id === openId ? "▾" : "▸"}</span>` +
     `<span class="meth ${t.method.toLowerCase()}">${esc(t.method)}</span>` +
     `<span class="hpath">${esc(t.path)}</span>` +
     // The message, not just the status: scanning a list for the request that
@@ -192,24 +206,46 @@ function draw(host: HTMLElement, ctx: TabContext): void {
   // which is what scrolls. The rows start below the sticky filter bar and the
   // facet strip, so the window is offset by the wrapper's position rather than
   // measured from zero.
-  const { first, count: take } = windowRange(
-    rows.length,
-    host.scrollTop,
-    host.clientHeight || 0,
-    wrap.offsetTop,
-  );
+  //
+  // Windowing is suspended while a request is open, because an open detail is a
+  // row of unknown height and every offset here is arithmetic on a fixed one.
+  // The store keeps 100 traces and the threshold is 200, so in practice this
+  // draws the same whole list it would have drawn anyway; the guard is for the
+  // correlated-group case that can fold more rows than traces.
+  const openId = store.openTraceId;
+  const { first, count: take } = openId
+    ? { first: 0, count: rows.length }
+    : windowRange(rows.length, host.scrollTop, host.clientHeight || 0, wrap.offsetTop);
   const slice = rows.slice(first, first + take);
   padTop.style.height = `${first * ROW_H}px`;
   padBot.style.height = `${Math.max(0, rows.length - first - take) * ROW_H}px`;
+  // The open request's detail rides in the list as its own item, so the
+  // reconciler keeps it across redraws — rebuilding it on every arriving request
+  // would collapse whatever the reader had scrolled to inside it.
+  const items: DrawItem[] = [];
+  for (const row of slice) {
+    items.push({ kind: "row", row });
+    if (openId && row.trace.id === openId && !row.child) {
+      items.push({ kind: "detail", trace: row.trace });
+    }
+  }
   const selectedId = store.selected?.id;
   reconcile(
     rowsHost,
-    slice,
-    rowKey,
-    (r) => {
-      const html = rowHtml(r, selectedId);
+    items,
+    itemKey,
+    (item) => {
+      if (item.kind === "detail") {
+        const node = document.createElement("div");
+        node.className = "hdetail";
+        renderSections(node, item.trace, ctx);
+        node.setAttribute("data-detail-rev", String(store.revision));
+        return node;
+      }
+      const html = rowHtml(item.row, selectedId, openId);
       const node = el(html);
       // Stamped on creation as well, so the very next update compares equal and
       // a row that has not changed is never rewritten.
@@ -220,13 +256,23 @@ function draw(host: HTMLElement, ctx: TabContext): void {
     // and the reconciler's job — keeping the *node* so scroll position and text
     // selection survive — is already done by the time this runs. The markup is
     // compared first, so a steady list generates no DOM writes at all.
-    (node, r) => {
-      const next = rowHtml(r, selectedId);
+    (node, item) => {
+      if (item.kind === "detail") {
+        // Redrawn only when the store actually moved. The sections below are
+        // whole tab renderers; running them on every keystroke in the filter box
+        // would be the most expensive thing in the panel.
+        const rev = String(store.revision);
+        if (node.getAttribute("data-detail-rev") === rev) return;
+        renderSections(node, item.trace, ctx);
+        node.setAttribute("data-detail-rev", rev);
+        return;
+      }
+      const next = rowHtml(item.row, selectedId, openId);
       if (node.getAttribute("data-html") === next) return;
       const fresh = el(next);
       node.className = fresh.className;
       node.replaceChildren(...Array.from(fresh.childNodes));
-      node.setAttribute("data-idx", String(r.index));
+      node.setAttribute("data-idx", String(item.row.index));
       node.setAttribute("data-html", next);
     },
   );
@@ -235,6 +281,7 @@ function draw(host: HTMLElement, ctx: TabContext): void {
 export const allTab: TabView = {
   id: "all",
   label: "All",
+  scope: "session",
   live: true,
   volatile: true,
   standsAlone: true,

package/src/client/tabs/app.ts CHANGED Viewed

@@ -134,6 +134,7 @@ function appTab(
 ): TabView {
   return {
     id: `app:${id}`,
+    scope: "session",
     label,
     standsAlone: true,
     volatile: true,

package/src/client/tabs/cache.ts CHANGED Viewed

@@ -13,6 +13,7 @@ function opClass(op: CacheEntry["op"]): string {
 export const cacheTab: TabView = {
   id: "cache",
   label: "Cache",
+  scope: "request",
   badge: ({ trace }) => (trace ? { count: trace.cache?.length ?? 0 } : undefined),

package/src/client/tabs/channel.ts CHANGED Viewed

@@ -10,7 +10,7 @@
  */
 import type { TraceChannelDescriptor, TraceChannelEntry } from "../../RequestTrace.ts";
 import { buildPathTree, type PathTreeNode } from "../tree.ts";
-import { chipFor, copyBtn, esc, fmtCell } from "../ui/format.ts";
+import { chipFor, copyBtn, esc, fmt, fmtCell } from "../ui/format.ts";
 import type { TabView } from "./types.ts";
 /** `key: value` spans for every field the descriptor named as meta. */
@@ -51,7 +51,7 @@ function asRows(rows: TraceChannelEntry[], c: TraceChannelDescriptor): string {
           `<div class="chead">` +
           (badge ? chipFor(badge, isWarn) : "") +
           flagChips(r, c.flags) +
-          `<span class="dim" style="font-size:10px">+${r.offsetMs}ms</span>` +
+          `<span class="dim" style="font-size:10px">+${fmt(r.offsetMs)}</span>` +
           copyBtn(JSON.stringify(r, null, 2), "Copy entry") +
           `</div>` +
           (title && title !== badge ? `<div class="cttl">${esc(title)}</div>` : "") +
@@ -90,7 +90,7 @@ function asTable(rows: TraceChannelEntry[], c: TraceChannelDescriptor): string {
                 `</td>`,
             )
             .join("") +
-          `<td class="dim">+${r.offsetMs}ms</td></tr>`
+          `<td class="dim">+${fmt(r.offsetMs)}</td></tr>`
         );
       })
       .join("") +
@@ -110,7 +110,7 @@ function asKv(rows: TraceChannelEntry[], c: TraceChannelDescriptor): string {
         .join("");
       return (
         `<div class="sec"><div class="stitle">` +
-        `${esc(heading || "Entry")} · +${r.offsetMs}ms` +
+        `${esc(heading || "Entry")} · +${fmt(r.offsetMs)}` +
         copyBtn(JSON.stringify(r, null, 2), "Copy entry") +
         `</div><table class="kv">${cells}</table></div>`
       );
@@ -230,6 +230,7 @@ export function channelTab(c: TraceChannelDescriptor): TabView {
   return {
     id: `channel:${c.id}`,
     label: c.label,
+    scope: "request",
     badge: ({ trace }) => {
       const rows = trace?.channels?.[c.id] ?? [];

package/src/client/tabs/exceptions.ts CHANGED Viewed

@@ -28,6 +28,7 @@ function isVendorFrame(file: string): boolean {
 export const exceptionsTab: TabView = {
   id: "exceptions",
   label: "Exception",
+  scope: "request",
   badge: ({ trace }) => (trace?.exception ? { count: "!", warn: true } : undefined),

package/src/client/tabs/jobs.ts CHANGED Viewed

@@ -10,6 +10,7 @@ function icon(status: JobEntry["status"]): string {
 export const jobsTab: TabView = {
   id: "jobs",
   label: "Jobs",
+  scope: "request",
   badge: ({ trace }) =>
     trace

package/src/client/tabs/live.ts ADDED Viewed

@@ -0,0 +1,66 @@
+/**
+ * The request happening now, opened for you.
+ *
+ * What the panel is for, most of the time, is the page you are looking at — and
+ * every other view made you go and find it first: open the panel, find the list,
+ * pick the top row. This is that request already open, and it follows: load a
+ * page, click something, and this is showing what just happened without a click
+ * of its own.
+ *
+ * It renders the same sections a request opens into in the list, so there is one
+ * description of what a request looks like rather than two that drift.
+ */
+import { dCls, esc, fmt, scCls } from "../ui/format.ts";
+import { renderSections } from "./sections.ts";
+import type { TabView } from "./types.ts";
+/**
+ * The newest request, rather than the pinned one.
+ *
+ * Pinning is how you hold still and read something older; this view is the
+ * opposite gesture, so it deliberately ignores it. The two disagreeing is the
+ * point — the status bar tells you what you pinned, this tells you what the page
+ * just did.
+ */
+export const liveTab: TabView = {
+  id: "live",
+  label: "Live",
+  scope: "session",
+  live: true,
+  volatile: true,
+  standsAlone: true,
+  badge({ store }) {
+    const t = store.traces[0];
+    if (!t) return undefined;
+    return t.exception ? { count: "!", warn: true } : undefined;
+  },
+  render(host, ctx) {
+    const trace = ctx.store.traces[0];
+    if (!trace) {
+      host.innerHTML =
+        '<p class="empty">Nothing yet — load a page or click something to see it here</p>';
+      return;
+    }
+    host.replaceChildren();
+    // Which request this is, since the sections below describe it but none of
+    // them names it.
+    const head = document.createElement("div");
+    head.className = "lvhead";
+    head.innerHTML =
+      `<span class="meth ${esc(trace.method.toLowerCase())}">${esc(trace.method)}</span>` +
+      `<span class="hpath">${esc(trace.path)}</span>` +
+      `<span class="sc ${scCls(trace.statusCode)}">${trace.statusCode || "—"}</span>` +
+      `<span class="${dCls(trace.durationMs) || "dim"}">${fmt(trace.durationMs)}</span>` +
+      `<span class="dim">${trace.queries.length}q</span>` +
+      (trace.warnings.length ? '<span class="chip warn">N+1</span>' : "");
+    host.appendChild(head);
+    const body = document.createElement("div");
+    renderSections(body, trace, ctx);
+    host.appendChild(body);
+  },
+};

package/src/client/tabs/logs.ts CHANGED Viewed

@@ -5,6 +5,7 @@ import type { TabView } from "./types.ts";
 export const logsTab: TabView = {
   id: "logs",
   label: "Logs",
+  scope: "request",
   badge: ({ trace }) => {
     const logs = trace?.logs ?? [];

package/src/client/tabs/mail.ts CHANGED Viewed

@@ -29,6 +29,7 @@ function preview(m: MailEntry): string {
 export const mailTab: TabView = {
   id: "mail",
   label: "Mail",
+  scope: "request",
   badge: ({ trace }) => (trace ? { count: trace.mail?.length ?? 0 } : undefined),

package/src/client/tabs/queries.ts CHANGED Viewed

@@ -59,6 +59,7 @@ function queryRow(q: QuerySpan, peak: number, editor: EditorSettings): string {
 export const queriesTab: TabView = {
   id: "queries",
   label: "Queries",
+  scope: "request",
   badge: ({ trace }) =>
     trace

package/src/client/tabs/request.ts CHANGED Viewed

@@ -11,7 +11,7 @@
  * survive the redirect, is the user id set" are all answered by the keys, and the
  * values are the request's real state.
  */
-import { copyBtn, esc, scCls } from "../ui/format.ts";
+import { copyBtn, esc } from "../ui/format.ts";
 import type { TabView } from "./types.ts";
 function kvTable(pairs: Record<string, string>): string {
@@ -39,6 +39,7 @@ function section(title: string, pairs: Record<string, string>): string {
 export const requestTab: TabView = {
   id: "request",
   label: "Request",
+  scope: "request",
   render(host, { trace }) {
     const t = trace!;
@@ -47,12 +48,11 @@ export const requestTab: TabView = {
     const responseHeaders = t.responseHeaders ?? {};
     const session = t.session ?? [];
-    const statusLine =
-      `<div class="rcard">` +
-      `<span class="meth ${t.method.toLowerCase()}">${esc(t.method)}</span> ` +
-      `<b>${esc(t.path)}</b> ` +
-      `<span class="sc ${scCls(t.statusCode)}">${t.statusCode || "—"}</span>` +
-      `</div>`;
+    // No status line here. This view was once a tab of its own and had to say
+    // which request it was describing; it is now a section of that request, and
+    // whatever opened it — the row in the list, the header in Live — has already
+    // said the method, the path and the status directly above. Repeating them
+    // read as a second heading competing with the real one.
     const sessionKeys = session.length
       ? `<div class="chips">` +
@@ -62,7 +62,6 @@ export const requestTab: TabView = {
         `No session on this request — or no session middleware installed</p>`;
     host.innerHTML =
-      statusLine +
       section("Query Params", params) +
       section("Request Headers", headers) +
       section("Response Headers", responseHeaders) +

package/src/client/tabs/sections.ts ADDED Viewed

@@ -0,0 +1,115 @@
+/**
+ * A request, drawn as its own small set of tabs.
+ *
+ * Twelve request-scoped tabs in the panel's main strip is twelve headings that
+ * are empty for most requests and answer a question you can only ask about a
+ * request you have already picked. They belong to the request, so they are drawn
+ * inside it — by calling the views themselves, since a `TabView` is already
+ * "draw this trace into this element", which is exactly what a section is.
+ * Nothing here reimplements a view.
+ *
+ * Tabs rather than a stack, because the sections are alternatives: you are
+ * reading the queries *or* the headers *or* the waterfall, and stacking them
+ * makes you scroll past two to reach the third. Only the ones with something to
+ * say appear, so the strip is also the summary — a request with a Queries, a
+ * Logs and an Exception tab has already told you what happened before you click
+ * anything.
+ *
+ * Shared by the request list, where a row opens into its own detail, and by the
+ * Live view, which shows the newest request without your having to open anything.
+ */
+import type { RequestTrace } from "../../RequestTrace.ts";
+import { esc } from "../ui/format.ts";
+import type { TabContext, TabView } from "./types.ts";
+/** Whether a view drew anything beyond its own "nothing here" line. */
+export function isEmptyRender(body: HTMLElement): boolean {
+  if (!body.textContent?.trim()) return true;
+  const kids = Array.from(body.children);
+  return kids.length > 0 && kids.every((k) => k.classList.contains("empty"));
+}
+interface Drawn {
+  view: TabView;
+  badge: ReturnType<NonNullable<TabView["badge"]>>;
+  body: HTMLElement;
+}
+/**
+ * Render every request-scoped view that has something to say about `trace`.
+ *
+ * A view is asked for its count first and skipped when it counts nothing — the
+ * queries view renders a stats strip even for a request that ran none, and a
+ * "Queries 0" heading over it is exactly the empty furniture this replaces. What
+ * survives that is rendered and then dropped anyway if what came back is only the
+ * view's own empty-state line, so a request that sent no mail has no Mail tab
+ * rather than a tab holding the word "none".
+ *
+ * Every surviving body is kept in the DOM and hidden rather than re-rendered on
+ * each switch: they are whole tab renderers, and the flick between two of them
+ * should cost nothing.
+ */
+export function renderSections(hostEl: HTMLElement, trace: RequestTrace, ctx: TabContext): void {
+  hostEl.replaceChildren();
+  const drawn: Drawn[] = [];
+  for (const view of ctx.sections ?? []) {
+    const badge = view.badge?.({ trace, store: ctx.store });
+    if (badge && Number(badge.count) === 0) continue;
+    const body = document.createElement("div");
+    body.className = "dsec-body";
+    try {
+      view.render(body, { trace, store: ctx.store });
+    } catch {
+      // A view that throws must not take the request it belongs to with it.
+      continue;
+    }
+    if (isEmptyRender(body)) continue;
+    drawn.push({ view, badge, body });
+  }
+  if (!drawn.length) {
+    hostEl.innerHTML = `<p class="empty">Nothing else was recorded for this request</p>`;
+    return;
+  }
+  const activeId = activeSection(
+    ctx.store.sectionTab,
+    drawn.map((d) => d.view.id),
+  );
+  const strip = document.createElement("div");
+  strip.className = "dsecs";
+  strip.innerHTML = drawn
+    .map(({ view, badge }) => {
+      const count = badge
+        ? `<span class="dsec-n${badge.warn ? " warn" : ""}">${esc(String(badge.count))}</span>`
+        : "";
+      return (
+        `<button class="dsect${view.id === activeId ? " on" : ""}" ` +
+        `data-sec="${esc(view.id)}">${esc(view.label)}${count}</button>`
+      );
+    })
+    .join("");
+  hostEl.appendChild(strip);
+  for (const { view, body } of drawn) {
+    const pane = document.createElement("div");
+    pane.className = "dsec-pane";
+    if (view.id !== activeId) pane.style.display = "none";
+    pane.appendChild(body);
+    hostEl.appendChild(pane);
+  }
+}
+/**
+ * Which section to show: the one you were reading, or the first this request has.
+ *
+ * Falling back rather than clearing the preference — move from a request with
+ * queries to one without and you get its first section, but the one after that
+ * with queries again puts you back where you were.
+ */
+export function activeSection(preferred: string, available: string[]): string {
+  return available.includes(preferred) ? preferred : (available[0] ?? "");
+}

package/src/client/tabs/timeline.ts CHANGED Viewed

@@ -55,6 +55,7 @@ const KEY: Array<[string, string]> = [
 export const timelineTab: TabView = {
   id: "timeline",
   label: "Timeline",
+  scope: "request",
   render(host, { trace, store }) {
     const t = trace!;

package/src/client/tabs/types.ts CHANGED Viewed

@@ -12,6 +12,11 @@ export interface TabContext {
   /** The pinned or live trace, or null before any traffic. */
   trace: RequestTrace | null;
   store: Store;
+  /**
+   * The request-scoped views, for the list to render inside whichever request is
+   * open. Absent in a test that renders one tab on its own.
+   */
+  sections?: TabView[];
 }
 /** The count beside a tab's label, and whether it should read as a warning. */
@@ -23,6 +28,18 @@ export interface TabBadge {
 export interface TabView {
   id: string;
   label: string;
+  /**
+   * Whether this describes one request or the session.
+   *
+   * `"request"` is not a tab at all: it is a section of the request you opened
+   * in the list. Twelve of these in the strip is twelve tabs that are empty for
+   * most requests and answer a question you can only ask about a request you
+   * have already picked — so they are rendered inside its row instead, and only
+   * when they have something to say. `"session"` earns a tab, because it keeps
+   * reading while you move between requests: the list itself, and a plugin that
+   * owns live browser state.
+   */
+  scope: "request" | "session";
   /**
    * Show the live dot while connected. For the tab whose contents change on
    * their own rather than only when you pick a different request.

package/src/client/ui/format.ts CHANGED Viewed

@@ -27,9 +27,28 @@ export function esc(s: unknown): string {
   return String(s ?? "").replace(/[&<>"']/g, (c) => ESCAPES[c]!);
 }
-/** A duration, in the largest unit that stays readable. */
+/** Drop the trailing zeros a fixed-precision number leaves behind: `3.0` → `3`. */
+function _trim(text: string): string {
+  return text.includes(".") ? text.replace(/0+$/, "").replace(/\.$/, "") : text;
+}
+/**
+ * A duration, at a precision worth reading.
+ *
+ * Precision scales with magnitude, because the interesting digits move: at 400ms
+ * nobody cares about the decimal, and at 0.4ms the decimal is the whole number.
+ * Both ends were wrong before. This interpolated the value raw, so anything
+ * measured with `performance.now()` printed its full float — the status bar read
+ * `3.6370999999926426ms` — while anything a caller had already rounded printed
+ * `0ms` for a query that plainly took time.
+ */
 export function fmt(ms: number): string {
-  return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
+  if (!Number.isFinite(ms) || ms < 0) return "—";
+  if (ms === 0) return "0ms";
+  if (ms >= 1000) return `${_trim((ms / 1000).toFixed(2))}s`;
+  if (ms >= 100) return `${Math.round(ms)}ms`;
+  if (ms >= 1) return `${_trim(ms.toFixed(1))}ms`;
+  return `${_trim(ms.toFixed(2))}ms`;
 }
 /** A byte count as KB or MB. */

package/src/client/ui/shell.ts CHANGED Viewed

@@ -66,21 +66,35 @@ export function mountShell(opts: ShellOptions): void {
   // Rebuilt per render because channels arrive over the wire and plugins register
   // whenever their own package is ready — the set is not known at start.
+  /** Every view the section showing can offer, before scope decides where it goes. */
+  function everyTab(): TabView[] {
+    if (store.section === "app") return APP_TABS;
+    return [...tabs, ...store.channels.map(channelTab), ...registry.panels.map(pluginTab)];
+  }
   /**
    * The tabs for the section showing.
    *
-   * Channels and plugins belong to the request stream — they are per-request
-   * data — so they only appear alongside it. The App section is a fixed six.
+   * Only the session-scoped ones. Everything that describes a single request —
+   * its queries, its logs, its channels — is a section of that request in the
+   * list rather than a tab of its own, so the strip is what you can look at
+   * rather than a dozen headings that are empty until you have picked something.
    */
   function allTabs(): TabView[] {
-    if (store.section === "app") return APP_TABS;
-    return [...tabs, ...store.channels.map(channelTab), ...registry.panels.map(pluginTab)];
+    return everyTab().filter((t) => t.scope === "session");
+  }
+  /** The views rendered inside whichever request is open. */
+  function requestTabs(): TabView[] {
+    return everyTab().filter((t) => t.scope === "request");
   }
   function pluginTab(p: DevtoolsRegistry["panels"][number]): TabView {
     return {
       id: `plugin:${p.id}`,
       label: p.title,
+      // Live browser state, which keeps reading as you move between requests.
+      scope: "session",
       // A plugin owns its data and its DOM; the panel cannot know when either
       // moved, so it redraws whenever anything else did and on explicit refresh.
       volatile: true,
@@ -91,7 +105,7 @@ export function mountShell(opts: ShellOptions): void {
       },
       render(el) {
         try {
-          p.render(el);
+          p.render(el, { trace: store.selected });
         } catch {
           // A broken extension tab must not take the panel with it.
           el.innerHTML = '<p class="empty">Panel error</p>';
@@ -106,7 +120,7 @@ export function mountShell(opts: ShellOptions): void {
   }
   function ctx(): TabContext {
-    return { trace: store.selected, store };
+    return { trace: store.selected, store, sections: requestTabs() };
   }
   // ── Render ──────────────────────────────────────────────────────────────────
@@ -132,6 +146,23 @@ export function mountShell(opts: ShellOptions): void {
   function applyTheme(): void {
     wrap.classList.toggle("light", isLightTheme(store.theme));
     if (!standalone) panel.style.height = `${store.height}px`;
+    reserveSpace();
+  }
+  /**
+   * Give the host page back the strip the panel covers.
+   *
+   * The panel is fixed to the bottom of the viewport, so without this the last
+   * 32px of a page — or the panel's full height when open — is behind it and
+   * cannot be scrolled to. The value is written as a custom property as well as
+   * the padding, so an app that would rather move something else of its own can
+   * read `--zt-dt-height` instead.
+   */
+  function reserveSpace(): void {
+    if (standalone) return;
+    const height = wrap.getBoundingClientRect().height;
+    document.documentElement.style.setProperty("--zt-dt-height", `${height}px`);
+    document.body.style.paddingBottom = `${height}px`;
   }
   function renderBar(): void {
@@ -339,8 +370,24 @@ export function mountShell(opts: ShellOptions): void {
       return;
     }
+    // A view inside the request being read. Checked before the row, since the
+    // strip sits inside the detail the row opened.
+    const sec = target.closest("[data-sec]") as HTMLElement | null;
+    if (sec?.dataset["sec"]) {
+      store.setSectionTab(sec.dataset["sec"]);
+      return;
+    }
+    // The list carries its own Clear, beside the filter it belongs with.
+    if (target.closest('[data-action="clear"]')) {
+      transport.clear();
+      return;
+    }
+    // Opening a request is the whole navigation now: its queries, logs, timeline
+    // and channels are sections of it rather than tabs you go and find.
     const row = target.closest("[data-idx]") as HTMLElement | null;
-    if (row) select(store.traces[Number(row.dataset["idx"])] ?? null);
+    if (row) store.toggleOpen(store.traces[Number(row.dataset["idx"])] ?? null);
   });
   content.addEventListener("input", (e: Event) => {
@@ -391,6 +438,7 @@ export function mountShell(opts: ShellOptions): void {
       // Leave the host page a strip of itself: a panel dragged to full height is
       // one you cannot get out of by dragging.
       panel.style.height = `${Math.max(MIN_HEIGHT, Math.min(next, window.innerHeight - 60))}px`;
+      reserveSpace();
     };
     const up = (): void => {
       grip.classList.remove("dragging");
@@ -457,7 +505,7 @@ export function mountShell(opts: ShellOptions): void {
     if (!rows.length) return;
     const at = rows.findIndex((r) => r.trace.id === store.selected?.id);
     const next = at === -1 ? 0 : Math.min(rows.length - 1, Math.max(0, at + delta));
-    select(rows[next]!.trace, false);
+    select(rows[next]!.trace);
   }
   // Alt+D stays global — it is how you reach a panel that does not have focus.
@@ -474,15 +522,16 @@ export function mountShell(opts: ShellOptions): void {
     if (standalone) return; // nothing to collapse into
     store.setOpen(!store.open);
     panel.style.display = store.open ? "flex" : "none";
+    reserveSpace();
     if (store.open) {
       wrap.focus({ preventScroll: true });
       renderContent(true);
     }
   }
-  function select(trace: RequestTrace | null, switchTab = true): void {
+  function select(trace: RequestTrace | null): void {
     if (!trace) return;
-    store.select(trace, { switchTab });
+    store.select(trace);
   }
   // ── Extension panels ────────────────────────────────────────────────────────

package/src/client/ui/theme.ts CHANGED Viewed

@@ -13,14 +13,17 @@
 const TOKENS = `
 #wrap {
   --bg: #1a1b26; --surf: #24283b; --card: #2f3452; --bdr: #3b4261;
-  --text: #c0caf5; --muted: #565f89; --purple: #7aa2f7;
+  /* --muted carries labels, hints and every inactive tab. At the palette's own
+     #565f89 that is 2.35:1 on --surf — below AA for text of any size, and this
+     is 10–11px text. Lifted until it clears 4.5:1 while staying recessive. */
+  --text: #c0caf5; --muted: #8790bd; --purple: #7aa2f7;
   --green: #9ece6a; --yellow: #e0af68; --red: #f7768e;
   --cyan: #7dcfff; --orange: #ff9e64;
   --childbg: rgba(0,0,0,.15);
 }
 #wrap.light {
   --bg: #f4f4f8; --surf: #e8e9f0; --card: #dcdee8; --bdr: #c0c4d4;
-  --text: #343b58; --muted: #6b7192; --purple: #34548a;
+  --text: #343b58; --muted: #565c7d; --purple: #34548a;
   --green: #33635c; --yellow: #8f5e15; --red: #c64343;
   --cyan: #0f4b6e; --orange: #965027;
   --childbg: rgba(0,0,0,.05);
@@ -35,7 +38,18 @@ ${TOKENS}
   color: var(--text);
 }
 #wrap:focus { outline: none; }
-#wrap:focus-visible { outline: none; }
+/* The container itself takes focus on open and should not draw a ring for it.
+   Anything a person actually tabs to must — the panel used to suppress focus
+   everywhere, which left keyboard navigation invisible. */
+#wrap :focus-visible {
+  outline: 2px solid var(--purple);
+  outline-offset: -2px;
+  border-radius: 2px;
+}
+/* Numbers line up only if the digits are the same width. Durations sit in a
+   right-aligned column, and proportional digits are what made its left edge
+   ragged from row to row. */
+.num, .dur, .meth, .stat .sval, .tlbl { font-variant-numeric: tabular-nums; }
 /* ── utility colours ──────────────────────────────────────────────────────── */
 .green  { color: var(--green);  }
 .yellow { color: var(--yellow); }
@@ -60,6 +74,10 @@ ${TOKENS}
 .meth.post   { color: var(--cyan);   }
 .meth.put, .meth.patch { color: var(--yellow); }
 .meth.delete { color: var(--red);    }
+/* Not an HTTP method: a Flow action, which arrives over the socket against a
+   synthetic GET of its own page. Its own colour so the list does not read as two
+   loads of that page. */
+.meth.flow   { color: var(--purple); }
 .bpath { max-width: 280px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 12px; }
 .sc   { font-weight: 700; font-size: 11px; flex-shrink: 0; }
 .sc.ok    { color: var(--green);  }
@@ -257,7 +275,45 @@ ${TOKENS}
 .tmark.chan  { background: var(--yellow); }
 .ttxt  { flex: 2; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 10px; }
 .tkey  { display: flex; gap: 10px; flex-wrap: wrap; padding: 6px 12px; font-size: 10px; color: var(--muted); }
-.tkey i { display: inline-block; width: 8px; height: 8px; border-radius: 2px; margin-right: 3px; vertical-align: middle; font-style: normal; }
+/* position:static undoes .tmark, which the legend swatch reuses for its colour.
+   .tmark is absolutely positioned for the waterfall, and in the legend — whose
+   rows are not positioned — that sent every swatch to the nearest positioned
+   ancestor, leaving seven squares stacked above their own labels. */
+.tkey i { position: static; display: inline-block; width: 8px; height: 8px; border-radius: 2px; margin-right: 3px; vertical-align: middle; font-style: normal; }
+/* ── an open request ──────────────────────────────────────────────────────── */
+.lvhead {
+  display: flex; align-items: baseline; gap: 8px; padding: 7px 12px;
+  border-bottom: 1px solid var(--bdr); background: var(--surf);
+  position: sticky; top: 0; z-index: 1;
+}
+.hchev { width: 12px; flex-shrink: 0; color: var(--muted); text-align: center; }
+.hdetail {
+  background: var(--childbg); border-bottom: 1px solid var(--bdr);
+  border-left: 2px solid var(--purple);
+}
+/* The request's own tab strip — alternatives, not a stack you scroll past. */
+.dsecs {
+  display: flex; gap: 2px; align-items: center; flex-wrap: wrap;
+  padding: 4px 10px; border-bottom: 1px solid var(--bdr); background: var(--surf);
+}
+.dsect {
+  display: inline-flex; align-items: center; gap: 4px;
+  background: none; border: 0; border-radius: 3px; cursor: pointer;
+  padding: 3px 7px; font: inherit; font-size: 11px; color: var(--muted);
+}
+.dsect:hover { color: var(--text); background: var(--card); }
+.dsect.on { color: var(--text); background: var(--card); font-weight: 700; }
+.tbtn {
+  background: none; border: 1px solid var(--bdr); border-radius: 3px;
+  color: var(--muted); cursor: pointer; padding: 2px 8px; font: inherit; font-size: 11px;
+  flex-shrink: 0;
+}
+.tbtn:hover { color: var(--text); border-color: var(--muted); }
+.dsec-n {
+  background: var(--card); color: var(--text); border-radius: 6px;
+  padding: 0 5px; font-size: 10px; font-variant-numeric: tabular-nums;
+}
+.dsec-n.warn { background: var(--red); color: var(--bg); }
 /* ── generic channel rows ─────────────────────────────────────────────────── */
 .crow  { padding: 7px 12px; border-bottom: 1px solid var(--bdr); }
 .crow.warn { border-left: 3px solid var(--yellow); }

package/src/tracing.ts CHANGED Viewed

@@ -94,11 +94,16 @@ export function _bufPush<T>(map: WeakMap<object, T[]>, ctx: object, item: T): vo
 const _channels = new Map<string, TraceChannelDescriptor>();
-/** Every channel declared so far, in display order. */
+/**
+ * Every channel that wants a tab, in display order.
+ *
+ * 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.
+ */
 export function traceChannels(): TraceChannelDescriptor[] {
-  return [...(_channels.values() as Iterable<TraceChannelDescriptor>)].sort(
-    (a, b) => (a.order ?? 100) - (b.order ?? 100) || a.label.localeCompare(b.label),
-  );
+  return [...(_channels.values() as Iterable<TraceChannelDescriptor>)]
+    .filter((c) => !c.hidden)
+    .sort((a, b) => (a.order ?? 100) - (b.order ?? 100) || a.label.localeCompare(b.label));
 }
 /** @internal — drop every declared channel (provider teardown, tests). */
@@ -164,6 +169,25 @@ export interface TraceSink {
    * picks up the entries already buffered for the request in flight.
    */
   record(ctx: object, channel: string, entry: Record<string, unknown>): void;
+  /**
+   * Turn a context into a trace, for work that never was an HTTP request.
+   *
+   * Traces are normally finalised from core's `RequestHandled` / `RequestFailed`,
+   * which covers everything the HTTP kernel serves and nothing else. A Flow action
+   * arrives over a WebSocket and runs against its own `HttpContext` — as do queue
+   * jobs and scheduled tasks — so no HTTP lifecycle event ever fires for it, and
+   * without this call everything buffered against that context (its channel rows,
+   * but equally its queries, its logs, its N+1 warnings) accumulated and was
+   * dropped unread. The Flow tab could then only ever report "no flow activity",
+   * which is exactly what it did.
+   *
+   * `method` labels the trace in the request list, because the underlying request
+   * is synthetic: Flow passes `FLOW` so an action is not read as a second `GET` of
+   * the page it acted on.
+   *
+   * Finalising happens once per context; a second call for the same one is ignored.
+   */
+  finalise(ctx: object, meta: { startMs: number; durationMs: number; method?: string }): void;
   bufferQuery(ctx: object, q: QuerySpan): void;
   bufferWarning(ctx: object, w: NPlusOneWarning): void;
   bufferMail(ctx: object, m: Omit<MailEntry, "offsetMs">): void;
@@ -186,6 +210,9 @@ export const traceSink: TraceSink = {
       absMs: Date.now(),
     });
   },
+  finalise(ctx: object, meta: { startMs: number; durationMs: number; method?: string }): void {
+    _finaliseTrace(ctx as HttpContext, meta.startMs, meta.durationMs, null, meta.method);
+  },
   bufferQuery(ctx: object, q: QuerySpan): void {
     // The call site is captured here rather than at the emit site because here
     // is the only place that knows whether anyone is recording. `skip` is 0: the
@@ -303,6 +330,7 @@ function _buildTrace(
   startMs: number,
   durationMs: number,
   exception: ExceptionInfo | null,
+  method?: string,
 ): RequestTrace {
   const queryParams: Record<string, string> = {};
   ctx.url.searchParams.forEach((v, k) => {
@@ -335,7 +363,7 @@ function _buildTrace(
   return {
     id: crypto.randomUUID().slice(0, 12),
     requestId: ctx.requestId,
-    method: ctx.request.method.toUpperCase(),
+    method: (method ?? ctx.request.method).toUpperCase(),
     path: ctx.url.pathname,
     statusCode: ctx.response?.status ?? 0,
     startMs,
@@ -437,20 +465,35 @@ export function startDevtoolsTracing(): void {
   });
 }
+/**
+ * Contexts already turned into a trace.
+ *
+ * One trace per context, enforced here rather than trusted: the HTTP lifecycle
+ * finalises exactly once, but a context that finalises *itself* — a Flow action,
+ * a queue job — could also be claimed by something else, and the second call
+ * would push a duplicate carrying none of the evidence, since the first cleaned
+ * the buffers out. Weak so it holds no context alive.
+ */
+const _finalised = new WeakSet<object>();
 /** Merge buffered events into a trace and push it to the store (once per request). */
 function _finaliseTrace(
   ctx: HttpContext,
   startMs: number,
   durationMs: number,
   exception: ExceptionInfo | null,
+  method?: string,
 ): void {
+  if (_finalised.has(ctx)) return;
+  _finalised.add(ctx);
   // Internal framework paths are noise — skip them
   if (_isInternal(ctx.url.pathname)) {
     _cleanupBuffers(ctx);
     return;
   }
-  const trace = _buildTrace(ctx, startMs, durationMs, exception);
+  const trace = _buildTrace(ctx, startMs, durationMs, exception, method);
   _cleanupBuffers(ctx);
   traceStore().push(trace);
 }