@zerotal/devtools 1.6.2 → 1.7.0

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,65 @@
+/**
+ * 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.
+ */
+
+/** 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). */
+  render: (el: HTMLElement) => 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,311 @@
+/**
+ * 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;
+  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;
+  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";
+    this.tab = saved.tab ?? "queries";
+    this.appTab = saved.appTab ?? "app:routes";
+    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,
+      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;
+  }
+
+  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, { switchTab = false } = {}): void {
+    this.selected = trace;
+    this.live = false;
+    this.pending = 0;
+    if (switchTab && this.tab === "all") this.tab = "queries";
+    this.persist();
+    this.changed();
+  }
+
+  /** 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();
+  }
+}