@zerotal/devtools 1.6.3 → 1.7.0

package/src/client/tabs/request.ts

@@ -0,0 +1,76 @@
+/**
+ * Both halves of the exchange: what came in, what went out, and what the session
+ * was holding while it happened.
+ *
+ * Headers are an allowlist, not a denylist, because a trace is persisted —
+ * `cookie` and `authorization` are the request's credentials, and a header nobody
+ * thought to deny is a header on disk for a day. `devtools.headers` opens up the
+ * ones you are actually debugging.
+ *
+ * The session shows **key names only**. "Is the CSRF token there, did the flash
+ * 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 type { TabView } from "./types.ts";
+
+function kvTable(pairs: Record<string, string>): string {
+  const rows = Object.entries(pairs)
+    .map(([k, v]) => `<tr><td>${esc(k)}</td><td>${esc(v)}</td></tr>`)
+    .join("");
+  return `<table class="kv">${rows || `<tr><td colspan="2" class="dim" style="padding:6px 12px">None</td></tr>`}</table>`;
+}
+
+/** The whole block as `name: value` lines, which is what you paste into a curl. */
+function asText(pairs: Record<string, string>): string {
+  return Object.entries(pairs)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join("\n");
+}
+
+function section(title: string, pairs: Record<string, string>): string {
+  return (
+    `<div class="sec"><div class="stitle">${esc(title)} (${Object.keys(pairs).length})` +
+    copyBtn(asText(pairs), `Copy ${title.toLowerCase()}`) +
+    `</div>${kvTable(pairs)}</div>`
+  );
+}
+
+export const requestTab: TabView = {
+  id: "request",
+  label: "Request",
+
+  render(host, { trace }) {
+    const t = trace!;
+    const params = t.queryParams ?? {};
+    const headers = t.headers ?? {};
+    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>`;
+
+    const sessionKeys = session.length
+      ? `<div class="chips">` +
+        session.map((k) => `<span class="chip">${esc(k)}</span>`).join("") +
+        `</div>`
+      : `<p class="dim" style="padding:2px 0 4px">` +
+        `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) +
+      `<div class="sec"><div class="stitle">Session keys (${session.length})` +
+      copyBtn(session.join("\n"), "Copy keys") +
+      `</div>${sessionKeys}` +
+      `<p class="dim" style="font-size:10px;margin-top:6px">` +
+      `Names only — the values are this request's real state, and a trace is kept for a day.` +
+      `</p></div>`;
+  },
+};

package/src/client/tabs/timeline.ts

@@ -0,0 +1,132 @@
+/**
+ * Everything the request did, on one waterfall.
+ *
+ * Every entry already carries an offset from the request start; the waterfall is
+ * what makes "what was waiting on what" legible instead of a column of numbers
+ * you have to order in your head.
+ */
+import { esc, fmt } from "../ui/format.ts";
+import type { ClientMetric } from "../metrics.ts";
+import type { TabView } from "./types.ts";
+
+/**
+ * What the browser measured, above what the server did.
+ *
+ * Kept visibly separate rather than merged into the waterfall: these describe
+ * the *page*, not this request, and drawing them on the same track would claim a
+ * relationship that is not there. Shown anyway, because server duration reported
+ * as if it were the user's experience is the panel's most misleading number.
+ */
+function clientStrip(metrics: ClientMetric[]): string {
+  if (!metrics.length) return "";
+  return (
+    `<div class="stats">` +
+    metrics
+      .map(
+        (m) =>
+          `<div class="stat" title="${esc(m.detail)}">` +
+          `<div class="slbl">${esc(m.label)}</div>` +
+          `<div class="sval">${fmt(m.value)}</div></div>`,
+      )
+      .join("") +
+    `</div>` +
+    `<div class="dim" style="font-size:10px;padding:4px 12px">` +
+    `Measured in the browser, for this page load — not for this request.</div>`
+  );
+}
+
+interface Span {
+  at: number;
+  dur: number;
+  kind: string;
+  text: string;
+}
+
+const KEY: Array<[string, string]> = [
+  ["query", "Queries"],
+  ["cache", "Cache"],
+  ["mail", "Mail"],
+  ["job", "Jobs"],
+  ["chan", "Channels"],
+  ["log", "Logs"],
+  ["warn", "Warnings"],
+];
+
+export const timelineTab: TabView = {
+  id: "timeline",
+  label: "Timeline",
+
+  render(host, { trace, store }) {
+    const t = trace!;
+    const spans: Span[] = [];
+
+    for (const q of t.queries) {
+      spans.push({
+        at: Math.max(0, q.startMs - t.startMs),
+        dur: q.durationMs,
+        kind: "query",
+        text: q.sql,
+      });
+    }
+    for (const c of t.cache ?? []) {
+      spans.push({ at: c.offsetMs, dur: c.durationMs, kind: "cache", text: `${c.op} ${c.key}` });
+    }
+    for (const m of t.mail ?? []) {
+      spans.push({ at: m.offsetMs, dur: m.durationMs, kind: "mail", text: m.subject });
+    }
+    for (const j of t.jobs ?? []) {
+      spans.push({ at: j.offsetMs, dur: j.durationMs, kind: "job", text: j.className });
+    }
+    for (const l of t.logs ?? []) {
+      spans.push({
+        at: l.offsetMs,
+        dur: 0,
+        kind: l.level === "error" || l.level === "warn" ? "warn" : "log",
+        text: l.args.join(" "),
+      });
+    }
+    for (const [id, rows] of Object.entries(t.channels ?? {})) {
+      const desc = store.channels.find((c) => c.id === id);
+      for (const r of rows) {
+        const titleKey = desc?.title ?? desc?.badge;
+        spans.push({
+          at: r.offsetMs,
+          dur: typeof r["durationMs"] === "number" ? (r["durationMs"] as number) : 0,
+          kind: "chan",
+          text: `${desc?.label ?? id}: ${titleKey ? String(r[titleKey] ?? "") : ""}`,
+        });
+      }
+    }
+
+    const client = clientStrip(store.clientMetrics);
+
+    if (!spans.length) {
+      host.innerHTML =
+        client + '<p class="empty">Nothing recorded on the timeline for this request</p>';
+      return;
+    }
+
+    spans.sort((a, b) => a.at - b.at);
+    const total = Math.max(1, t.durationMs);
+
+    host.innerHTML =
+      client +
+      `<div class="tkey">` +
+      KEY.map(([k, lbl]) => `<span><i class="tmark ${k}"></i>${lbl}</span>`).join("") +
+      `</div><div>` +
+      spans
+        .map((s) => {
+          const left = Math.min(99, (s.at / total) * 100);
+          const width = Math.max(0.6, Math.min(100 - left, (s.dur / total) * 100));
+          return (
+            `<div class="trow">` +
+            `<span class="tlbl dim">+${s.at}ms</span>` +
+            `<span class="ttrack"><span class="tmark ${s.kind}" style="left:${left}%;width:${width}%"></span></span>` +
+            `<span class="ttxt dim" title="${esc(s.text)}">${esc(s.text)}</span>` +
+            `</div>`
+          );
+        })
+        .join("") +
+      `</div>`;
+  },
+};

package/src/client/tabs/types.ts

@@ -0,0 +1,51 @@
+/**
+ * What a tab is.
+ *
+ * Every tab in the panel — built-in, channel, or plugin — is reduced to this, so
+ * the shell has one loop for the tab strip and one call for the content instead
+ * of a switch that grows a case per feature. Adding a tab is adding a file.
+ */
+import type { RequestTrace } from "../../RequestTrace.ts";
+import type { Store } from "../state.ts";
+
+export interface TabContext {
+  /** The pinned or live trace, or null before any traffic. */
+  trace: RequestTrace | null;
+  store: Store;
+}
+
+/** The count beside a tab's label, and whether it should read as a warning. */
+export interface TabBadge {
+  count: number | string;
+  warn?: boolean;
+}
+
+export interface TabView {
+  id: string;
+  label: string;
+  /**
+   * Show the live dot while connected. For the tab whose contents change on
+   * their own rather than only when you pick a different request.
+   */
+  live?: boolean;
+  /**
+   * Redraw whenever anything in the store moved, not only when the selected
+   * trace changed. The default is the cheaper one: a tab that reads one trace is
+   * redrawn when that trace changes and left alone otherwise.
+   */
+  volatile?: boolean;
+  /**
+   * Render even when nothing is selected. Only the request list has anything to
+   * say before the first request arrives.
+   */
+  standsAlone?: boolean;
+  badge?(ctx: TabContext): TabBadge | undefined;
+  render(host: HTMLElement, ctx: TabContext): void;
+  /**
+   * Redraw for a scroll of the content host, without a store change.
+   *
+   * Only a tab that windows its rows needs this — for everything else the
+   * browser scrolls what is already drawn.
+   */
+  onScroll?(host: HTMLElement, ctx: TabContext): void;
+}

package/src/client/transport.ts

@@ -0,0 +1,81 @@
+/**
+ * The wire: one `EventSource` and three JSON endpoints.
+ *
+ * Split out because it is the only part of the panel that talks to the server,
+ * and keeping it apart is what lets every tab be a pure function of the store.
+ * `EventSource` reconnects on its own timer, so there is no retry loop here —
+ * only the connection flag the bar's dot reads.
+ */
+import type { RequestTrace, TraceChannelDescriptor } from "../RequestTrace.ts";
+import type { EditorName } from "../editor.ts";
+import type { Store } from "./state.ts";
+
+/** What the SSE stream sends. */
+type Frame =
+  | {
+      type: "history";
+      data: RequestTrace[];
+      channels?: TraceChannelDescriptor[];
+      capacity?: number;
+      editor?: EditorName | null;
+      editorPathMap?: Record<string, string>;
+    }
+  | { type: "trace"; data: RequestTrace }
+  | { type: "clear" };
+
+export interface Transport {
+  /** Ask the server to drop its history. The `clear` frame comes back over SSE. */
+  clear(): void;
+  /** Close the stream. Called when the panel removes itself from the page. */
+  close(): void;
+}
+
+/**
+ * Connect the store to the stream.
+ *
+ * @param base - The devtools endpoint root, without a trailing slash.
+ * @param store - Mutated as frames arrive; it announces its own changes.
+ */
+export function connect(base: string, store: Store): Transport {
+  const sse = new EventSource(`${base}/sse`);
+
+  sse.onopen = () => {
+    store.connected = true;
+    store.changed();
+  };
+
+  sse.onerror = () => {
+    store.connected = false;
+    store.changed();
+  };
+
+  sse.onmessage = (e: MessageEvent<string>) => {
+    let frame: Frame;
+    try {
+      frame = JSON.parse(e.data) as Frame;
+    } catch {
+      // A truncated frame is the stream's problem, not the panel's; the next one
+      // will be whole.
+      return;
+    }
+    if (frame.type === "history") {
+      store.loadHistory(frame.data, frame.channels ?? [], frame.capacity, {
+        editor: frame.editor ?? null,
+        editorPathMap: frame.editorPathMap ?? {},
+      });
+    } else if (frame.type === "trace") {
+      store.addTrace(frame.data);
+    } else {
+      store.clear();
+    }
+  };
+
+  return {
+    clear() {
+      void fetch(`${base}/api/clear`, { method: "POST" });
+    },
+    close() {
+      sse.close();
+    },
+  };
+}

package/src/client/tree.ts

@@ -0,0 +1,138 @@
+/**
+ * Turning flat records into the nested views the panel draws.
+ *
+ * Two shapings, both pure and both testable without a DOM: dotted prop paths
+ * into a tree, and a set of traces into correlated groups.
+ */
+import type { RequestTrace, TraceChannelDescriptor } from "../RequestTrace.ts";
+
+/** A node of a dotted-path tree: a leaf with attributes, a branch with children, or both. */
+export interface PathTreeNode {
+  children: Map<string, PathTreeNode>;
+  /** The node's own attributes, or null for a branch nothing was recorded against. */
+  attrs: Record<string, unknown> | null;
+}
+
+/**
+ * Split a map of dotted paths into the tree the dots already describe.
+ *
+ * `user.name` and `user.email` are two entries in a flat record and one branch
+ * with two leaves on screen — which is the difference between reading a prop bag
+ * and scanning one. A path can be both: `user` may carry attributes of its own
+ * *and* have children, so a branch keeps its `attrs` rather than being treated as
+ * a container.
+ *
+ * @param paths - Dotted path → that node's attributes.
+ */
+export function buildPathTree(paths: Array<[string, unknown]>): Map<string, PathTreeNode> {
+  const root = new Map<string, PathTreeNode>();
+  for (const [path, attrs] of paths) {
+    let level = root;
+    const parts = path.split(".");
+    parts.forEach((part, i) => {
+      let node = level.get(part);
+      if (!node) {
+        node = { children: new Map(), attrs: null };
+        level.set(part, node);
+      }
+      if (i === parts.length - 1) {
+        node.attrs = attrs && typeof attrs === "object" ? (attrs as Record<string, unknown>) : {};
+      }
+      level = node.children;
+    });
+  }
+  return root;
+}
+
+/**
+ * The value that groups this trace with others, from whichever channel declared
+ * a `traceGroup` field. Null when nothing correlates it.
+ *
+ * One user action can be several requests — a visit, then the deferred-prop loads
+ * it triggers — and listing them as unrelated siblings is how the thing you are
+ * debugging scrolls off the top. Which field says so is the channel's to declare,
+ * so this stays free of any package's vocabulary.
+ *
+ * The id is prefixed with the channel's, so two channels that both correlate
+ * cannot collide on a shared value.
+ */
+export function traceGroupKey(
+  trace: RequestTrace,
+  channels: TraceChannelDescriptor[],
+): string | null {
+  for (const c of channels) {
+    if (!c.traceGroup) continue;
+    const value = trace.channels?.[c.id]?.[0]?.[c.traceGroup];
+    if (value != null && value !== "") return `${c.id}:${String(value)}`;
+  }
+  return null;
+}
+
+/** One line of the All tab: a trace, its index in the full list, and its nesting. */
+export interface TraceRow {
+  trace: RequestTrace;
+  /** Index into the *unfiltered* trace list, so a click still selects the right one. */
+  index: number;
+  /** True for a follow-up shown under its group head. */
+  child: boolean;
+  /** The group this row heads, when it heads one. */
+  groupKey?: string;
+  /** How many follow-ups are folded under this head. */
+  groupSize?: number;
+}
+
+/**
+ * Flatten the filtered traces into the rows the All tab draws, folding correlated
+ * requests under the oldest of each set.
+ *
+ * A group takes the position of its *newest* member, so a batch still receiving
+ * follow-ups stays where you are looking rather than sinking as it grows. The
+ * head is its oldest member — the request that started it — because that is the
+ * one you meant to click.
+ *
+ * Kept separate from the rendering so the All tab's structure can be asserted on
+ * without a DOM, and so virtualisation has a flat array to window over.
+ */
+export function foldTraceRows(
+  matches: Array<{ trace: RequestTrace; index: number }>,
+  channels: TraceChannelDescriptor[],
+  expanded: ReadonlySet<string>,
+): TraceRow[] {
+  const order: string[] = [];
+  const groups = new Map<string, Array<{ trace: RequestTrace; index: number }>>();
+
+  for (const m of matches) {
+    // Uncorrelated traces get a key of their own so they never merge with each
+    // other — the fallback has to be unique, not shared.
+    const key = traceGroupKey(m.trace, channels) ?? `#${m.index}`;
+    let bucket = groups.get(key);
+    if (!bucket) {
+      groups.set(key, (bucket = []));
+      order.push(key);
+    }
+    bucket.push(m);
+  }
+
+  const rows: TraceRow[] = [];
+  for (const key of order) {
+    const members = groups.get(key)!;
+    if (members.length === 1) {
+      rows.push({ trace: members[0]!.trace, index: members[0]!.index, child: false });
+      continue;
+    }
+    // Oldest last, because the list is newest-first.
+    const head = members[members.length - 1]!;
+    const rest = members.slice(0, -1);
+    rows.push({
+      trace: head.trace,
+      index: head.index,
+      child: false,
+      groupKey: key,
+      groupSize: rest.length,
+    });
+    if (expanded.has(key)) {
+      for (const m of rest) rows.push({ trace: m.trace, index: m.index, child: true });
+    }
+  }
+  return rows;
+}

package/src/client/ui/format.ts

@@ -0,0 +1,118 @@
+/**
+ * The small formatters every tab shares.
+ *
+ * They were nine closures inside `DevTools.start()`, which meant a tab could not
+ * be moved into a file of its own without taking copies of them with it. Nothing
+ * here touches the DOM or the store — it is all value-in, string-out.
+ */
+import { editorUrl, shortLocation, type SourceLocation } from "../../editor.ts";
+import type { EditorSettings } from "../state.ts";
+
+const ESCAPES: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+/**
+ * HTML-escape a value for interpolation into markup **or** an attribute.
+ *
+ * Quotes are escaped as well as angle brackets, which is what makes it safe for
+ * `title="…"` and for the mail preview's `srcdoc="…"` — the panel renders text it
+ * did not write, on the app's own origin.
+ */
+export function esc(s: unknown): string {
+  return String(s ?? "").replace(/[&<>"']/g, (c) => ESCAPES[c]!);
+}
+
+/** A duration, in the largest unit that stays readable. */
+export function fmt(ms: number): string {
+  return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
+}
+
+/** A byte count as KB or MB. */
+export function fmtMem(b: number): string {
+  return b >= 1_048_576 ? `${(b / 1_048_576).toFixed(1)} MB` : `${(b / 1024).toFixed(0)} KB`;
+}
+
+/** The colour class for a request duration — empty for "unremarkable". */
+export function dCls(ms: number): string {
+  return ms > 1000 ? "red" : ms > 300 ? "yellow" : "";
+}
+
+/** The colour class for a status code. */
+export function scCls(s: number): string {
+  return s >= 500 ? "srv" : s >= 400 ? "cli" : s >= 300 ? "redir" : "ok";
+}
+
+/** One channel value, as a single line of text. */
+export function fmtCell(v: unknown): string {
+  if (v === null || v === undefined) return "";
+  if (typeof v === "object") return JSON.stringify(v) ?? "";
+  return String(v);
+}
+
+/**
+ * A badge chip, accented by hashing its own text.
+ *
+ * `partial` and `deferred` need to be tellable apart at a glance, and the only
+ * way to do that without devtools holding a list of every value every package
+ * might use is to derive the colour from the value itself. Stable per value, so
+ * a badge keeps its colour between requests.
+ */
+export function chipFor(text: string, warn: boolean): string {
+  if (warn) return `<span class="chip warn">${esc(text)}</span>`;
+  let hash = 0;
+  for (let i = 0; i < text.length; i++) hash = (hash * 31 + text.charCodeAt(i)) >>> 0;
+  return `<span class="chip a${hash % 6}">${esc(text)}</span>`;
+}
+
+/**
+ * A copy-to-clipboard button carrying its own payload.
+ *
+ * The text rides in a data attribute rather than being read back out of the
+ * rendered DOM, because what you want on the clipboard is rarely what is on
+ * screen — the SQL without its duration bar, the log line without its offset.
+ * The shell's delegated handler does the copying; this only marks the target.
+ */
+export function copyBtn(text: string, label = "Copy"): string {
+  if (!text) return "";
+  return `<button class="cpy" data-copy="${esc(text)}" title="${esc(label)}">⧉</button>`;
+}
+
+/** The table an N+1 warning's SQL reads from, for the suppression call. */
+export function tableFrom(sql: string): string {
+  return /from\s+[`'"[]?(\w+)/i.exec(sql)?.[1] ?? "table_name";
+}
+
+/**
+ * A source location, as a link to the editor when there is one to make.
+ *
+ * The panel renders a location the same way everywhere it appears — a query's
+ * call site, a log line's, a stack frame, a prop's render source — because the
+ * gesture is the same one every time: this is where it happened, go there.
+ *
+ * Falls back to plain text when `editor` is null or the location has no file. A
+ * location worth showing is still worth showing when it cannot be opened.
+ *
+ * @param location - Where, or null/undefined for nothing at all.
+ * @param editor - The panel's resolved editor settings.
+ * @param extraClass - Appended to the element's class, for per-surface spacing.
+ */
+export function sourceLink(
+  location: SourceLocation | null | undefined,
+  editor: EditorSettings,
+  extraClass = "",
+): string {
+  if (!location?.file) return "";
+  const label = shortLocation(location);
+  const title = location.function
+    ? `${location.function} — ${location.file}:${location.line}`
+    : `${location.file}:${location.line}`;
+  const url = editorUrl(location, editor.editor, editor.editorPathMap);
+  const cls = `src${extraClass ? ` ${extraClass}` : ""}`;
+  if (!url) return `<span class="${cls}" title="${esc(title)}">${esc(label)}</span>`;
+  return `<a class="${cls} link" href="${esc(url)}" title="${esc(title)}">${esc(label)}</a>`;
+}

package/src/client/ui/render.ts

@@ -0,0 +1,87 @@
+/**
+ * A keyed list reconciler, in about sixty lines and with no dependency.
+ *
+ * The panel used to redraw `#content` wholesale on every trace, which on the All
+ * tab — the one that redraws most, because every request changes it — threw away
+ * the scroll position, every open `<details>`, and the caret in the filter box,
+ * fifty times a second under load. Keying the rows means an arriving request
+ * inserts one node and touches nothing else.
+ *
+ * Deliberately not a virtual DOM. The panel is bundled on demand and injected
+ * into arbitrary apps, so it stays dependency-free and small; a list diff is the
+ * only reconciliation any of this needs.
+ */
+
+/** Where a reconciler stores each child's identity. */
+const KEY_ATTR = "data-k";
+
+/**
+ * Make `host`'s element children match `items`, in order, reusing by key.
+ *
+ * A child whose key survives is moved rather than rebuilt, so anything the
+ * browser owns inside it — scroll offset, `<details>` state, an iframe's loaded
+ * document, text selection — survives with it.
+ *
+ * @param host - The element whose children are the list. Must hold nothing else.
+ * @param items - The list, in the order it should appear.
+ * @param keyOf - A stable identity per item. Two items must never share one.
+ * @param create - Build the element for an item seen for the first time.
+ * @param update - Bring a reused element up to date. Called for every survivor.
+ */
+export function reconcile<T>(
+  host: HTMLElement,
+  items: readonly T[],
+  keyOf: (item: T) => string,
+  create: (item: T) => HTMLElement,
+  update?: (el: HTMLElement, item: T) => void,
+): void {
+  const existing = new Map<string, HTMLElement>();
+  // Anything without a key was not put there by a previous reconcile — an empty
+  // state, a message the host wrote directly — so it is not part of the list and
+  // has to go, or it lingers above the rows that replaced it.
+  const strays: Element[] = [];
+  for (const child of Array.from(host.children)) {
+    const key = child.getAttribute(KEY_ATTR);
+    if (key === null) strays.push(child);
+    else existing.set(key, child as HTMLElement);
+  }
+  for (const stray of strays) stray.remove();
+
+  // Walks forward through the host's children alongside `items`. Anything
+  // already in the right place is left untouched, which is what keeps a steady
+  // list from generating DOM writes at all.
+  let cursor: ChildNode | null = host.firstChild;
+
+  for (const item of items) {
+    const key = keyOf(item);
+    let el = existing.get(key);
+    if (el) {
+      existing.delete(key);
+      update?.(el, item);
+    } else {
+      el = create(item);
+      el.setAttribute(KEY_ATTR, key);
+    }
+    if (cursor === el) {
+      cursor = el.nextSibling;
+    } else {
+      host.insertBefore(el, cursor);
+    }
+  }
+
+  // Whatever the walk did not claim is gone from the list.
+  for (const el of existing.values()) el.remove();
+}
+
+/**
+ * Build an element from a markup string.
+ *
+ * The tabs are string builders — the shape they render is fixed and a template
+ * literal reads far better than twenty `createElement` calls — so the reconciler
+ * needs a way back from markup to a node it can key and move.
+ */
+export function el(html: string): HTMLElement {
+  const template = document.createElement("template");
+  template.innerHTML = html.trim();
+  return template.content.firstElementChild as HTMLElement;
+}