@zerotal/devtools 1.6.3 → 1.7.2

package/src/client/index.ts

@@ -0,0 +1,127 @@
+/**
+ * @zerotal/devtools — browser client
+ *
+ * Usage (in your app.js / frontend entry):
+ *   import { DevTools } from '@zerotal/devtools/client';
+ *   DevTools.start();
+ *
+ * Connects to the SSE stream served by DevtoolsInjectionMiddleware and renders a
+ * live floating panel. No script injection by the server is required.
+ *
+ * This file is only the wiring. The panel was one 1,400-line closure holding its
+ * state, its transport, its styles, eight renderers, and every helper — which
+ * made adding a tab an edit to the middle of it and made none of its logic
+ * testable. It is now a directory: {@link Store} holds the state,
+ * `transport.ts` owns the wire, `ui/shell.ts` owns the frame, and each tab is a
+ * file that exports a {@link TabView}. Both mount modes still run one set of
+ * renderers, and both extension doors are unchanged.
+ */
+import { Store } from "./state.ts";
+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";
+import { logsTab } from "./tabs/logs.ts";
+import { mailTab } from "./tabs/mail.ts";
+import { queriesTab } from "./tabs/queries.ts";
+import { requestTab } from "./tabs/request.ts";
+import { timelineTab } from "./tabs/timeline.ts";
+
+export interface DevtoolsClientOptions {
+  /** Base URL path for the devtools API. Default: '/__zerotal/devtools' */
+  endpoint?: string;
+  /**
+   * How the panel is mounted.
+   *
+   * `'floating'` (default) pins a collapsible bar to the bottom of the page.
+   * `'standalone'` fills the window and drops the collapse/close controls — the
+   * inspector dashboard. Both run the same renderers, so a tab added for one
+   * exists in the other.
+   */
+  mode?: "floating" | "standalone";
+  /** Element to mount into. Defaults to `document.body`. */
+  mount?: HTMLElement;
+}
+
+/**
+ * The built-in views, in strip order.
+ *
+ * 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 = [
+  liveTab,
+  allTab,
+  requestTab,
+  exceptionsTab,
+  queriesTab,
+  logsTab,
+  mailTab,
+  cacheTab,
+  jobsTab,
+  timelineTab,
+];
+
+export const DevTools = {
+  start(opts: DevtoolsClientOptions = {}): void {
+    if (typeof document === "undefined") return;
+    if (document.getElementById("__zerotal_dt__")) return;
+
+    const base = (opts.endpoint ?? "/__zerotal/devtools").replace(/\/$/, "");
+    const standalone = opts.mode === "standalone";
+
+    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();
+    });
+
+    mountShell({
+      base,
+      standalone,
+      mount: opts.mount ?? document.body,
+      store,
+      transport,
+      tabs: BUILT_IN,
+    });
+  },
+};
+
+// ── Public surface ────────────────────────────────────────────────────────────
+//
+// The panel is markup, and markup is awkward to assert on. What is exported here
+// is the part of it that is *logic*: a package contributing a channel can check
+// how its rows will filter, fold, and nest without a browser.
+//
+// Deliberately not everything the directory exports. `TabView`, the theme choice,
+// and the All tab's own mechanics are internal contracts this package reserves
+// the right to change — the tests that cover them import them by path, which is
+// what a same-package test should do rather than widening the API to be reachable.
+
+export type { DevtoolsPanelPlugin } from "./registry.ts";
+export type { Facets } from "./filter.ts";
+export type { PathTreeNode, TraceRow } from "./tree.ts";
+
+export {
+  matchesFilter,
+  matchesFacets,
+  traceMatches,
+  methodsPresent,
+  noFacets,
+  facetsActive,
+  SLOW_MS,
+} from "./filter.ts";
+export { buildPathTree, traceGroupKey, foldTraceRows } from "./tree.ts";

package/src/client/metrics.ts

@@ -0,0 +1,98 @@
+/**
+ * What the *browser* measured, alongside what the server did.
+ *
+ * The panel reports server duration as though it were the user's experience. It
+ * is not: a 12ms response that the browser spends 900ms parsing, laying out, and
+ * painting is a slow page, and nothing in the trace said so. The panel already
+ * runs JavaScript on the page and had never asked the one API that knows.
+ *
+ * Read once, after the load event, from the Performance timeline — no polling,
+ * no observer left running, nothing sampled per frame. It is a report on the
+ * document, so there is exactly one of it per page load.
+ */
+
+/** One browser-side measurement, in the shape the panel's stat grid draws. */
+export interface ClientMetric {
+  label: string;
+  /** Milliseconds. Rounded — sub-millisecond precision here is noise. */
+  value: number;
+  /** Longer text for the row's tooltip. */
+  detail: string;
+}
+
+/**
+ * The phases of a page load, as the Navigation Timing entry names them.
+ *
+ * Chosen for what a developer can act on: time to the first byte is the server
+ * plus the network, DOM interactive is parsing, and load is everything the page
+ * asked for. The rest of the entry is either derived from these or is about DNS
+ * and TLS, which is not what a request inspector is for.
+ */
+function navigationMetrics(nav: PerformanceNavigationTiming): ClientMetric[] {
+  const out: ClientMetric[] = [];
+  const add = (label: string, value: number, detail: string): void => {
+    if (Number.isFinite(value) && value > 0) out.push({ label, value: Math.round(value), detail });
+  };
+  add("TTFB", nav.responseStart - nav.requestStart, "Request sent → first byte back");
+  add("Response", nav.responseEnd - nav.responseStart, "First byte → last byte");
+  add("DOM interactive", nav.domInteractive - nav.responseEnd, "Parsing the document");
+  add("DOM complete", nav.domComplete - nav.domInteractive, "Subresources and deferred scripts");
+  add("Load", nav.loadEventEnd - nav.startTime, "Navigation start → load event");
+  return out;
+}
+
+/**
+ * Paint timings, when the browser recorded them.
+ *
+ * First Contentful Paint is the one number that most closely tracks "did that
+ * feel fast", and it is the only Web Vital available without a library and
+ * without leaving an observer running for the life of the page.
+ */
+function paintMetrics(): ClientMetric[] {
+  try {
+    return performance
+      .getEntriesByType("paint")
+      .filter((e) => e.name === "first-contentful-paint")
+      .map((e) => ({
+        label: "First paint",
+        value: Math.round(e.startTime),
+        detail: "Navigation start → first content on screen",
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Everything the browser can tell us about this page load, or an empty list.
+ *
+ * Empty rather than throwing on every browser that does not implement the API,
+ * and empty before the load event, when the numbers are not final.
+ */
+export function collectClientMetrics(): ClientMetric[] {
+  try {
+    const [nav] = performance.getEntriesByType("navigation") as PerformanceNavigationTiming[];
+    // `loadEventEnd` is 0 until the load event has actually fired; reading before
+    // then produces negative durations rather than an error.
+    if (!nav || nav.loadEventEnd <= 0) return paintMetrics();
+    return [...navigationMetrics(nav), ...paintMetrics()];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Run `fn` once the page has finished loading.
+ *
+ * A panel injected into a page that has already loaded — which is what happens
+ * on a hot reload — would otherwise wait for an event that has been and gone.
+ */
+export function onceLoaded(fn: () => void): void {
+  if (document.readyState === "complete") {
+    // Not synchronously: `loadEventEnd` is stamped *after* the handlers run, so
+    // reading it in the same turn as a just-fired load event reads a zero.
+    setTimeout(fn, 0);
+    return;
+  }
+  window.addEventListener("load", () => setTimeout(fn, 0), { once: true });
+}

package/src/client/registry.ts

@@ -0,0 +1,87 @@
+/**
+ * The extension door other packages come through.
+ *
+ * A package adds its own tab to the injected panel — a unified dev tool across
+ * the framework — by calling `window.__zerotalDevtools?.register(panel)` from its
+ * own browser code (`@zerotal/flow`'s time-travel timeline is the live consumer).
+ * The panel renders the extra tab and calls `panel.render(el)` when it is shown;
+ * `refresh(id)` lets the extension push a live update.
+ *
+ * The registry is created lazily by whichever runs first — this panel or an
+ * extension — so registration is order-independent. That shape is public API and
+ * 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>`. */
+  id: string;
+  /** Tab label. */
+  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).
+   *
+   * `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 {
+  panels: DevtoolsPanelPlugin[];
+  /** @internal set by the host panel — called when a panel registers. */
+  _emit: ((p: DevtoolsPanelPlugin) => void) | null;
+  /** @internal set by the host panel — called on refresh(id). */
+  _refresh: ((id?: string) => void) | null;
+  register(panel: DevtoolsPanelPlugin): DevtoolsPanelPlugin;
+  refresh(id?: string): void;
+}
+
+// `window.__zerotalDevtools` is the documented extension point above, so it
+// belongs on `Window` rather than behind a cast at each use. Declared, not
+// asserted: an extension reading it from its own code gets the same type.
+declare global {
+  interface Window {
+    __zerotalDevtools?: DevtoolsRegistry;
+  }
+}
+
+/** Get-or-create the global devtools extension registry. */
+export function ensureRegistry(): DevtoolsRegistry {
+  const w = window;
+  if (!w.__zerotalDevtools) {
+    w.__zerotalDevtools = {
+      panels: [],
+      _emit: null,
+      _refresh: null,
+      register(panel: DevtoolsPanelPlugin) {
+        this.panels.push(panel);
+        this._emit?.(panel);
+        return panel;
+      },
+      refresh(id?: string) {
+        this._refresh?.(id);
+      },
+    };
+  }
+  return w.__zerotalDevtools;
+}

package/src/client/state.ts

@@ -0,0 +1,350 @@
+/**
+ * Everything the panel knows, in one place, with a change signal.
+ *
+ * It used to be sixteen `let`s inside `DevTools.start()` and a scattering of
+ * `renderBar(); if (open) renderContent();` after each assignment — which meant
+ * adding a piece of state meant finding every place that had to redraw because of
+ * it, and forgetting one was a panel that showed something stale. Now a mutation
+ * calls {@link Store.changed} and the shell decides what to redraw.
+ */
+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 type { ThemeChoice } from "./ui/theme.ts";
+
+/**
+ * How the panel turns a captured location into a link.
+ *
+ * Sent by the server rather than configured in the browser: the paths come from
+ * the process that recorded them, so the process that recorded them is what
+ * knows how to rewrite them.
+ */
+export interface EditorSettings {
+  editor: EditorName | null;
+  editorPathMap: Record<string, string>;
+}
+
+/**
+ * The slice of state that outlives a reload.
+ *
+ * Which tab you were on, what you had filtered to, how tall you dragged the
+ * panel, and whether it was open are answers to "where was I", and every reload
+ * used to throw them away — which on a page you are reloading *because* you are
+ * debugging it is the wrong moment to lose them.
+ */
+export interface PersistedUi {
+  open: boolean;
+  section: Section;
+  tab: string;
+  appTab: string;
+  /** The view showing inside an open request. */
+  sectionTab: string;
+  filter: string;
+  facets: Facets;
+  height: number;
+  theme: ThemeChoice;
+}
+
+/**
+ * Which half of the panel is showing.
+ *
+ * `requests` is the trace stream — what the app just did. `app` is the framework
+ * map — what the app *is*. Two sections rather than fifteen tabs in one strip:
+ * they answer different questions, and a strip you have to scroll to reach the
+ * routes list is one you stop reaching for.
+ */
+export type Section = "requests" | "app";
+
+const UI_KEY = "__zerotal_devtools_ui";
+
+/** Panel heights outside this range are a panel you cannot use. */
+export const MIN_HEIGHT = 120;
+export const DEFAULT_HEIGHT = 380;
+
+function loadUi(): Partial<PersistedUi> {
+  try {
+    const raw = localStorage.getItem(UI_KEY);
+    const parsed: unknown = raw ? JSON.parse(raw) : null;
+    return parsed && typeof parsed === "object" ? (parsed as Partial<PersistedUi>) : {};
+  } catch {
+    // Private mode, a disabled store, a half-written value — a dev panel that
+    // cannot remember its tab is fine; one that throws on boot is not.
+    return {};
+  }
+}
+
+function saveUi(state: PersistedUi): void {
+  try {
+    localStorage.setItem(UI_KEY, JSON.stringify(state));
+  } catch {
+    /* see above */
+  }
+}
+
+export class Store {
+  // ── Server state ────────────────────────────────────────────────────────────
+  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
+   * history frame lands; until then this matches the store's own default rather
+   * than being a number of the client's own that a configured capacity could not
+   * move.
+   */
+  capacity = 100;
+  /** Replaced by the app's real settings when the history frame lands. */
+  editor: EditorSettings = { editor: null, editorPathMap: {} };
+
+  // ── Session state ───────────────────────────────────────────────────────────
+  /** Following the newest request, rather than pinned to one you picked. */
+  live = true;
+  /** Traces that arrived while pinned — offered, never jumped to. */
+  pending = 0;
+  /** Correlated-request groups opened on the All tab. */
+  readonly expanded = new Set<string>();
+  /**
+   * What the browser measured for this page load.
+   *
+   * Per page, not per request — which is why they sit above the waterfall
+   * labelled as the browser's rather than being merged into it. A 12ms response
+   * the browser spends 900ms painting is a slow page, and the server trace
+   * cannot say so.
+   */
+  clientMetrics: ClientMetric[] = [];
+
+  // ── Persisted UI ────────────────────────────────────────────────────────────
+  open: boolean;
+  section: Section;
+  tab: string;
+  /** The App section's tab, kept apart so switching sections restores each one. */
+  appTab: string;
+  filter: string;
+  facets: Facets;
+  height: number;
+  theme: ThemeChoice;
+
+  /**
+   * Bumped on every change. A tab that must redraw whenever anything moved —
+   * rather than only when the selected trace changed — reads this into its cache
+   * key, which is how the All tab stays live while the others stay still.
+   */
+  revision = 0;
+
+  private readonly listeners = new Set<() => void>();
+
+  /**
+   * @param standalone - The dashboard has nothing to collapse into; it starts open.
+   * @param base - The devtools endpoint root, for the surfaces that fetch rather
+   *   than listen. The App section reads the framework map over it.
+   */
+  constructor(
+    standalone: boolean,
+    readonly base = "/__zerotal/devtools",
+  ) {
+    const saved = loadUi();
+    this.open = standalone || saved.open === true;
+    this.section = saved.section === "app" ? "app" : "requests";
+    // 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);
+    this.theme = saved.theme ?? "auto";
+  }
+
+  subscribe(fn: () => void): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  /** Announce a change. Every mutation ends here; nothing redraws without it. */
+  changed(): void {
+    this.revision++;
+    for (const fn of this.listeners) fn();
+  }
+
+  /** Write the durable slice out. Called from the mutations that touch it. */
+  persist(): void {
+    saveUi({
+      open: this.open,
+      section: this.section,
+      appTab: this.appTab,
+      tab: this.tab,
+      sectionTab: this.sectionTab,
+      filter: this.filter,
+      facets: this.facets,
+      height: this.height,
+      theme: this.theme,
+    });
+  }
+
+  // ── Derived ─────────────────────────────────────────────────────────────────
+
+  /**
+   * The traces the All tab shows, with their index in the full list.
+   *
+   * The index rides along because a click has to select the right trace after
+   * filtering, and because keyboard navigation steps through *this* list rather
+   * than through everything recorded.
+   */
+  visible(): Array<{ trace: RequestTrace; index: number }> {
+    const out: Array<{ trace: RequestTrace; index: number }> = [];
+    this.traces.forEach((trace, index) => {
+      if (traceMatches(trace, this.filter, this.facets)) out.push({ trace, index });
+    });
+    return out;
+  }
+
+  // ── Mutations ───────────────────────────────────────────────────────────────
+
+  /** The tab showing in the current section. */
+  get activeTab(): string {
+    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;
+    this[key] = tab;
+    this.persist();
+    this.changed();
+  }
+
+  setSection(section: Section): void {
+    if (this.section === section) return;
+    this.section = section;
+    this.persist();
+    this.changed();
+  }
+
+  setFilter(filter: string): void {
+    this.filter = filter;
+    this.persist();
+    this.changed();
+  }
+
+  setFacets(facets: Facets): void {
+    this.facets = facets;
+    this.persist();
+    this.changed();
+  }
+
+  setHeight(height: number): void {
+    this.height = Math.max(MIN_HEIGHT, Math.round(height));
+    this.persist();
+    this.changed();
+  }
+
+  setTheme(theme: ThemeChoice): void {
+    this.theme = theme;
+    this.persist();
+    this.changed();
+  }
+
+  setOpen(open: boolean): void {
+    this.open = open;
+    this.persist();
+    this.changed();
+  }
+
+  /** Pin a trace and stop following the newest. */
+  select(trace: RequestTrace | null): void {
+    this.selected = trace;
+    this.live = false;
+    this.pending = 0;
+    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;
+    this.pending = 0;
+    this.selected = this.traces[0] ?? null;
+    this.changed();
+  }
+
+  pin(): void {
+    this.live = false;
+    this.changed();
+  }
+
+  toggleGroup(key: string): void {
+    if (!this.expanded.delete(key)) this.expanded.add(key);
+    this.changed();
+  }
+
+  /** Apply the stream's opening frame. */
+  loadHistory(
+    traces: RequestTrace[],
+    channels: TraceChannelDescriptor[],
+    capacity?: number,
+    editor?: Partial<EditorSettings>,
+  ): void {
+    this.traces = traces;
+    this.channels = channels;
+    if (editor) this.editor = { ...this.editor, ...editor };
+    // An older server sends no capacity; keeping what we have then is better than
+    // trimming its history to a guess.
+    if (typeof capacity === "number" && capacity > 0) this.capacity = capacity;
+    if (this.live || !this.selected) this.selected = traces[0] ?? null;
+    this.changed();
+  }
+
+  /** Take one new trace off the stream. */
+  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++;
+    this.changed();
+  }
+
+  clear(): void {
+    this.traces = [];
+    this.selected = null;
+    this.pending = 0;
+    this.expanded.clear();
+    this.changed();
+  }
+}