@tinvar/react 0.0.0-stage → 0.4.1

package/src/telemetry.js

@@ -0,0 +1,851 @@
+// Client telemetry: how the page loaded, and what went wrong in its script,
+// reported to the server's /_vitals and /_errors (Tinvar\Observability
+// \TelemetryEndpoint).
+//
+// tinvar-spec.md, "Endpoints": "`/_vitals`, `/_errors` ... | `throttle:telemetry`,
+// CSRF | 16 KB bodies; route names checked against the manifest". So each
+// report is a same-origin POST carrying the CSRF header every other one
+// carries, under 16 KB, naming its page by route name -- which the server
+// holds to its route registry, and refuses when it is not one.
+//
+// The document's page is named by its page metadata's `route`: its route's
+// name, or the view of a page with none (ADR 0129). Failing that, by its
+// route token, whose payload is plain base64url JSON with the route name in
+// its `r`. A page the router mounts is named by its route token, or its view
+// where it has none. All of it is read without verifying, as the router
+// reads the session binding beside it (bindingOf), since nothing here
+// trusts it -- the server checks the name again. A page with no name at all
+// reports nothing.
+//
+// A visitor with no session -- a static page's, which no PHP rendered --
+// has no CSRF token, and reports with no cookie at all: the server takes a
+// report that rides no session without one, since there is no session for
+// a forged one to ride (ADR 0129).
+//
+// Vitals are measured with PerformanceObserver alone: LCP, FCP and TTFB as
+// the document loaded, CLS as its largest burst of layout shifts, INP from
+// event timing. Each page the reader is shown has its own: the document's,
+// and then each page a client navigation mounts, whose CLS and INP are
+// measured from its mount, and whose NAV is how long the navigation took,
+// from the visit's start to the page's mount -- LCP, FCP and TTFB exist
+// only for the document's load. A page's vitals are sent once, when it is
+// left for the next, or the first time the tab is hidden, filed under that
+// page's route and as a `document` or a `client` navigation.
+//
+// A static page carries its Content Security Policy in a meta element,
+// which can name nowhere to report to: a browser ignores report-uri and
+// report-to there. Its violations still reach the page as
+// `securitypolicyviolation` events, and those of the meta element's policy
+// are sent to /_reports, as the browser sends a header's, with no cookie.
+//
+// Errors come from the window's `error` and `unhandledrejection` events and
+// from the hooks an application hands React's root. Each is reduced to a
+// message, a digest, its kind, the same-origin script and line it came from
+// and a few frames of its stack -- never a cookie's or storage's contents,
+// nor the URL's query -- deduplicated, capped per page, filed under the page
+// on screen, and sent in a batch a moment later or when the page is hidden.
+//
+// A report that fails is dropped: telemetry about telemetry would be sent
+// through the thing that just failed.
+
+import { csrfHeaders } from './csrf.js';
+import { readPageMetadata } from './router.js';
+
+export const VITALS_PATH = '/_vitals';
+export const ERRORS_PATH = '/_errors';
+export const REPORTS_PATH = '/_reports';
+
+/** The server's cap on one report, in bytes. */
+export const MAX_BODY_BYTES = 16384;
+
+/** Errors reported for one page, at most; the rest are dropped. */
+export const MAX_ERRORS_PER_PAGE = 10;
+
+/** Errors in one report: the server takes no more. */
+export const MAX_ERRORS_PER_REPORT = 10;
+
+/** How long errors are gathered before they are sent, in milliseconds. */
+export const ERROR_DELAY_MS = 1000;
+
+/**
+ * The largest value of each vital the server believes: milliseconds, and a
+ * score for CLS. A vital past its ceiling is left out of the report, which
+ * the server would otherwise refuse whole.
+ */
+export const VITAL_CEILINGS = Object.freeze({
+  LCP: 120000,
+  INP: 120000,
+  CLS: 10,
+  FCP: 120000,
+  TTFB: 120000,
+  NAV: 120000,
+});
+
+/** Policy violations sent for one document, at most; the rest are dropped. */
+export const MAX_VIOLATIONS = 10;
+
+/** Where an error was seen. */
+const KINDS = new Set(['error', 'rejection', 'caught', 'uncaught', 'recoverable']);
+
+/** What is kept of an error: a message, and a few short frames. */
+const MAX_MESSAGE = 300;
+const MAX_STACK_LINES = 10;
+const MAX_STACK_LINE = 200;
+
+/** A route name, as the server allows one. */
+const ROUTE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+/** What a page's reports may be filed under: a route name, or a view. */
+const ROUTE_LABEL = /^[A-Za-z0-9_][A-Za-z0-9_.\/-]{0,127}$/;
+
+/** The label as given, when it is one; null otherwise. */
+const labelOf = (/** @type {unknown} */ value) =>
+  typeof value === 'string' && ROUTE_LABEL.test(value) ? value : null;
+
+/** A digest a server failure is shown under: the framework's, or React's. */
+const DIGEST = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** A stack frame's script and line: `at f (https://host/a.js:1:2)`, `f@https://host/a.js:1:2`. */
+const FRAME = /([a-z][a-z0-9+.-]*:\/\/[^\s()]+?|\/[^\s()]+?):(\d+):(\d+)\)?$/i;
+
+/** A browser's own word for an error in a script from another origin: nothing to go on. */
+const OPAQUE = 'Script error.';
+
+/**
+ * The route name a route token names, or null. Read without verifying: the
+ * server holds the name to its registry whatever this says.
+ *
+ * @param {string | null | undefined} token
+ * @returns {string | null}
+ */
+export function routeNameOf(token) {
+  if (typeof token !== 'string') return null;
+  const body = token.split('.')[1];
+  if (!body) return null;
+
+  try {
+    const route = JSON.parse(atob(body.replace(/-/g, '+').replace(/_/g, '/')))?.r;
+    return typeof route === 'string' && route.length <= 128 && ROUTE_NAME.test(route) ? route : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @typedef {{
+ *   router?: { routeTokens(): string[], currentView?(): string | null, on(name: string, fn: (event: CustomEvent) => void): () => void } | null,
+ *   window?: Window,
+ *   fetch?: typeof fetch,
+ *   vitals?: boolean,
+ *   errors?: boolean,
+ *   violations?: boolean,
+ * }} TelemetryOptions
+ *
+ * `router` is the page's client router: the page on screen is read from it,
+ * and an error is counted against the page it happened on. Without one, the
+ * document's own page metadata says which page this is.
+ */
+
+/** @param {TelemetryOptions} [options] */
+export function createTelemetry(options = {}) {
+  const win = options.window ?? globalThis.window;
+  const doc = win?.document;
+  const router = options.router ?? null;
+  const doFetch = options.fetch ?? ((url, init) => win.fetch(url, init));
+
+  let started = false;
+  let stopped = false;
+
+  /** Set once the session has ended on this client: nothing more is sent for it. */
+  let revoked = false;
+
+  /** @type {Array<() => void>} */
+  const teardown = [];
+
+  // ---------------------------------------------------------------- the page
+
+  /**
+   * The page on screen: what its reports are filed under, how it came to be
+   * shown -- the document's load, or a client navigation -- how long that
+   * navigation took, and whether its vitals have gone.
+   *
+   * @type {{ route: string | null, navigation: 'document' | 'client', nav: number | null, sent: boolean, interactionsBefore: number }}
+   */
+  let page = { route: null, navigation: 'document', nav: null, sent: false, interactionsBefore: 0 };
+
+  /** When the visit to the next page began, by the router's `start`. */
+  let visitStarted = /** @type {number | null} */ (null);
+
+  /** The route of the page on screen. */
+  function currentRoute() {
+    return page.route;
+  }
+
+  /** The route of a page the router has just mounted: its token's name, or its view. */
+  function mountedRoute() {
+    if (router === null) return null;
+    const [token] = router.routeTokens();
+    return routeNameOf(token) ?? labelOf(router.currentView?.() ?? null);
+  }
+
+  const now = () => win?.performance?.now?.() ?? 0;
+
+  // ------------------------------------------------------------------ sending
+
+  /**
+   * POSTs one report as every other request from script does -- with the
+   * session's CSRF token -- and outlives the page with `keepalive`, which
+   * sendBeacon cannot do with a header. A page with no token has no session
+   * to send it under, and sends it with no cookie at all, which the server
+   * takes without one (ADR 0129).
+   *
+   * @param {string} path
+   * @param {unknown} body
+   * @param {string} [type]
+   */
+  function post(path, body, type = 'application/json') {
+    if (revoked) return;
+    const headers = path === REPORTS_PATH ? {} : csrfHeaders(doc);
+    const sessionless = Object.keys(headers).length === 0;
+
+    try {
+      const sent = doFetch(path, {
+        method: 'POST',
+        keepalive: true,
+        credentials: sessionless ? 'omit' : 'same-origin',
+        headers: { 'Content-Type': type, ...headers },
+        body: JSON.stringify(body),
+      });
+      sent?.catch?.(() => {});
+    } catch {
+      // Dropped; see the top of this file.
+    }
+  }
+
+  // ------------------------------------------------------------------- vitals
+
+  /** What has been measured: raw entry times, worked into vitals at send. */
+  const measured = {
+    activationStart: 0,
+    ttfb: /** @type {number | null} */ (null),
+    fcp: /** @type {number | null} */ (null),
+    lcp: /** @type {number | null} */ (null),
+    cls: /** @type {number | null} */ (null),
+    clsWindow: 0,
+    clsWindowStart: 0,
+    clsLast: 0,
+    interactions: /** @type {Map<number, number>} */ (new Map()),
+    interactionCount: 0,
+    lastInteraction: 0,
+  };
+
+  /** When the page was first hidden: a paint after it was not one the reader saw load. */
+  let firstHidden = Infinity;
+
+  /** @type {Array<[PerformanceObserver, (entries: PerformanceEntryList) => void]>} */
+  const observers = [];
+
+  /** Whether layout shifts are measured here: a page's CLS starts at 0 where they are. */
+  let shiftsObserved = false;
+
+  /** The interactions the browser had counted when the page on screen was mounted. */
+  const interactionTotal = () => {
+    const count = /** @type {{ interactionCount?: number }} */ (win?.performance ?? {}).interactionCount;
+    return typeof count === 'number' && count > 0 ? count : 0;
+  };
+
+  /**
+   * @param {string} type
+   * @param {(entries: PerformanceEntryList) => void} handle
+   * @param {Record<string, unknown>} [more]
+   */
+  function observe(type, handle, more = {}) {
+    const Observer = win.PerformanceObserver;
+    if (typeof Observer !== 'function' || !Observer.supportedEntryTypes?.includes(type)) return false;
+    try {
+      const observer = new Observer((list) => handle(list.getEntries()));
+      observer.observe({ type, buffered: true, ...more });
+      observers.push([observer, handle]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function observeVitals() {
+    firstHidden = doc?.visibilityState === 'hidden' ? 0 : Infinity;
+
+    observe('navigation', (entries) => {
+      const navigation = /** @type {PerformanceNavigationTiming | undefined} */ (entries[0]);
+      if (!navigation) return;
+      measured.activationStart =
+        /** @type {{ activationStart?: number }} */ (navigation).activationStart ?? 0;
+      if (navigation.responseStart > 0) measured.ttfb = navigation.responseStart;
+    });
+
+    observe('paint', (entries) => {
+      for (const entry of entries) {
+        if (entry.name === 'first-contentful-paint' && entry.startTime < firstHidden)
+          measured.fcp = entry.startTime;
+      }
+    });
+
+    // The last candidate is the largest; the browser stops naming them once
+    // the reader interacts.
+    observe('largest-contentful-paint', (entries) => {
+      const last = entries[entries.length - 1];
+      if (last && last.startTime < firstHidden) measured.lcp = last.startTime;
+    });
+
+    // The largest session window of shifts: shifts less than a second apart,
+    // over five seconds at most, none just after the reader's own input.
+    shiftsObserved = observe('layout-shift', (entries) => {
+      for (const entry of /** @type {Array<PerformanceEntry & { value: number, hadRecentInput: boolean }>} */ (
+        entries
+      )) {
+        if (entry.hadRecentInput) continue;
+        const joins =
+          measured.clsWindow > 0 &&
+          entry.startTime - measured.clsLast < 1000 &&
+          entry.startTime - measured.clsWindowStart < 5000;
+        measured.clsWindow = joins ? measured.clsWindow + entry.value : entry.value;
+        if (!joins) measured.clsWindowStart = entry.startTime;
+        measured.clsLast = entry.startTime;
+        measured.cls = Math.max(measured.cls ?? 0, measured.clsWindow);
+      }
+    });
+    if (shiftsObserved) measured.cls ??= 0;
+
+    // Each interaction's latency is its slowest event; INP is the slowest
+    // interaction, setting one aside for every fifty -- the 98th percentile.
+    /** @param {PerformanceEntryList} entries */
+    const interactions = (entries) => {
+      for (const entry of /** @type {Array<PerformanceEntry & { interactionId?: number }>} */ (entries)) {
+        const id = entry.interactionId;
+        if (!id) continue;
+        if (!measured.interactions.has(id) && id > measured.lastInteraction) measured.interactionCount++;
+        measured.lastInteraction = Math.max(measured.lastInteraction, id);
+        measured.interactions.set(id, Math.max(measured.interactions.get(id) ?? 0, entry.duration));
+        // Only the longest few can be the answer; the rest are let go.
+        if (measured.interactions.size > 50) {
+          const kept = [...measured.interactions].sort((a, b) => b[1] - a[1]).slice(0, 10);
+          measured.interactions = new Map(kept);
+        }
+      }
+    };
+    observe('event', interactions, { durationThreshold: 40 });
+    observe('first-input', interactions);
+  }
+
+  /**
+   * The vitals of the page on screen as they stand: milliseconds, and a
+   * score for CLS. A vital past its ceiling, or not measured, is absent. A
+   * page a client navigation mounted has no LCP, FCP or TTFB of its own.
+   *
+   * @returns {Partial<Record<'LCP' | 'INP' | 'CLS' | 'FCP' | 'TTFB' | 'NAV', number>>}
+   */
+  function vitals() {
+    const since = (time) => (time === null ? null : Math.max(time - measured.activationStart, 0));
+    const latencies = [...measured.interactions.values()].sort((a, b) => b - a);
+    const counted = interactionTotal() - page.interactionsBefore;
+    const total = counted > 0 ? counted : measured.interactionCount;
+    const inp =
+      latencies.length === 0 ? null : latencies[Math.min(latencies.length - 1, Math.floor(total / 50))];
+
+    /** @type {Record<string, number | null>} */
+    const values =
+      page.navigation === 'document'
+        ? {
+            LCP: since(measured.lcp),
+            INP: inp ?? null,
+            CLS: measured.cls,
+            FCP: since(measured.fcp),
+            TTFB: since(measured.ttfb),
+          }
+        : { INP: inp ?? null, CLS: measured.cls, NAV: page.nav };
+
+    /** @type {Record<string, number>} */
+    const kept = {};
+    for (const [name, value] of Object.entries(values)) {
+      const ceiling = VITAL_CEILINGS[/** @type {keyof typeof VITAL_CEILINGS} */ (name)];
+      if (value === null || !Number.isFinite(value) || value < 0 || value > ceiling) continue;
+      kept[name] = name === 'CLS' ? Math.round(value * 10000) / 10000 : Math.round(value * 10) / 10;
+    }
+    return kept;
+  }
+
+  /**
+   * The page on screen's vitals, once: whatever the observers still hold is
+   * read first, as this page's. They go on observing, for the next page.
+   */
+  function sendVitals() {
+    if (page.sent || observers.length === 0) return;
+    page.sent = true;
+
+    for (const [observer, handle] of observers) {
+      try {
+        handle(observer.takeRecords());
+      } catch {
+        // An observer that cannot be read has nothing more to say.
+      }
+    }
+
+    const metrics = vitals();
+    if (page.route !== null && Object.keys(metrics).length > 0) {
+      post(VITALS_PATH, { route: page.route, navigation: page.navigation, metrics });
+    }
+  }
+
+  /**
+   * A client navigation mounted a page: the one it replaced has its vitals
+   * sent, and this one's are measured from now -- its layout shifts and its
+   * interactions, and how long the visit took.
+   */
+  function mounted() {
+    sendVitals();
+    const at = now();
+    page = {
+      route: mountedRoute(),
+      navigation: 'client',
+      nav: visitStarted === null ? null : Math.max(at - visitStarted, 0),
+      sent: false,
+      interactionsBefore: interactionTotal(),
+    };
+    visitStarted = null;
+    measured.cls = shiftsObserved ? 0 : null;
+    measured.clsWindow = 0;
+    measured.clsWindowStart = 0;
+    measured.clsLast = 0;
+    measured.interactions = new Map();
+    measured.interactionCount = 0;
+  }
+
+  // ---------------------------------------------------------- violations
+
+  /** The policy the document's meta element holds, read at start(): null where it has none. */
+  let metaPolicy = /** @type {string | null} */ (null);
+
+  /** Violations waiting to be sent, and what was sent already, by what it said. */
+  /** @type {Array<Record<string, unknown>>} */
+  let violations = [];
+  const violated = new Set();
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let violationTimer = null;
+
+  /**
+   * A URL as the server keeps it: no query, no fragment, no credentials; a
+   * keyword (`inline`, `eval`) as itself.
+   *
+   * @param {unknown} value
+   * @returns {string | undefined}
+   */
+  function bareUrl(value) {
+    if (typeof value !== 'string' || value === '') return undefined;
+    if (/^[a-z][a-z-]{0,31}$/.test(value)) return value;
+    try {
+      const url = new URL(value, win.location.href);
+      return `${url.protocol}//${url.host}${url.pathname}`.slice(0, 512);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * A violation of the meta element's policy, which no report-uri can name:
+   * sent to /_reports as a Reporting API report would be. Not one of a
+   * header's policy -- the browser reports those itself -- and none of its
+   * sample, which can hold the script it blocked.
+   *
+   * @param {SecurityPolicyViolationEvent} event
+   */
+  function violation(event) {
+    if (stopped || metaPolicy === null || String(event.originalPolicy).trim() !== metaPolicy) return;
+    const directive = typeof event.effectiveDirective === 'string' ? event.effectiveDirective : '';
+    const body = {
+      documentURL: bareUrl(event.documentURI),
+      blockedURL: bareUrl(event.blockedURI),
+      effectiveDirective: directive,
+      disposition: event.disposition === 'report' ? 'report' : 'enforce',
+      sourceFile: bareUrl(event.sourceFile),
+      lineNumber: Number.isInteger(event.lineNumber) ? event.lineNumber : undefined,
+      columnNumber: Number.isInteger(event.columnNumber) ? event.columnNumber : undefined,
+    };
+    const key = [directive, body.blockedURL, body.sourceFile, body.lineNumber].join('\u0000');
+    if (violated.has(key) || violated.size >= MAX_VIOLATIONS) return;
+    violated.add(key);
+
+    violations.push({ type: 'csp-violation', body });
+    violationTimer ??= win.setTimeout(flushViolations, ERROR_DELAY_MS);
+  }
+
+  function flushViolations() {
+    if (violationTimer !== null) win.clearTimeout(violationTimer);
+    violationTimer = null;
+    if (violations.length === 0) return;
+    post(REPORTS_PATH, violations.splice(0), 'application/reports+json');
+  }
+
+  // ------------------------------------------------------------------- errors
+
+  /** What has been reported for the page on screen, by what it said; and how many. */
+  let seen = new Set();
+  let reportedHere = 0;
+
+  /** Errors waiting to be sent, each with the route it happened on. */
+  /** @type {Array<{ route: string, error: Record<string, unknown> }>} */
+  let pending = [];
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+
+  /** Error objects already taken, by whichever way they came first. */
+  const taken = new WeakSet();
+
+  /** The value a hook is handing on to the browser's own reporting, not to be taken twice. */
+  let handingOn;
+
+  /**
+   * Reports an error for the page on screen. Nothing for a page with no
+   * route name, nothing past the page's cap, and nothing it has reported
+   * already.
+   *
+   * @param {unknown} error
+   * @param {string} [kind]
+   * @param {{ message?: unknown, filename?: unknown, lineno?: unknown }} [event]
+   */
+  function reportError(error, kind = 'error', event = {}) {
+    if (stopped || revoked || !KINDS.has(kind)) return;
+    if (error !== null && (typeof error === 'object' || typeof error === 'function')) {
+      if (taken.has(error)) return;
+      taken.add(error);
+    }
+
+    const route = currentRoute();
+    if (route === null || reportedHere >= MAX_ERRORS_PER_PAGE) return;
+
+    const described = describe(error, kind, event);
+    if (described === null) return;
+
+    const key = [kind, described.message, described.file ?? '', described.line ?? ''].join('\u0000');
+    if (seen.has(key)) return;
+    seen.add(key);
+    reportedHere++;
+
+    pending.push({ route, error: described });
+    timer ??= win.setTimeout(flushErrors, ERROR_DELAY_MS);
+  }
+
+  /**
+   * An error as it is reported: its message, the digest a server failure
+   * was shown under, the script and line it came from when that is this
+   * origin's, and a few frames.
+   *
+   * @param {unknown} error
+   * @param {string} kind
+   * @param {{ message?: unknown, filename?: unknown, lineno?: unknown }} event
+   * @returns {Record<string, unknown> | null}
+   */
+  function describe(error, kind, event) {
+    const message = messageOf(error, event.message);
+    if (message === null) return null;
+
+    const stack = typeof (/** @type {{ stack?: unknown }} */ (error)?.stack) === 'string' ? error.stack : '';
+    const where = typeof event.filename === 'string' && event.filename !== '' ? event : frameOf(stack);
+
+    /** @type {Record<string, unknown>} */
+    const described = { kind, message: withoutQueries(scrub(message)).slice(0, MAX_MESSAGE) };
+
+    const digest = /** @type {{ digest?: unknown }} */ (error)?.digest;
+    if (typeof digest === 'string' && DIGEST.test(digest)) described.digest = digest;
+
+    const file = sameOriginPath(where?.filename);
+    if (file !== null) {
+      described.file = file;
+      const line = Number(where.lineno);
+      if (Number.isInteger(line) && line >= 1 && line <= 10_000_000) described.line = line;
+    }
+
+    const frames = framesOf(stack);
+    if (frames !== '') described.stack = frames;
+
+    return described;
+  }
+
+  /**
+   * What an error says. Never a value's contents when it is not an error or
+   * a string: a rejected response, a record, whatever was thrown -- only
+   * what kind of thing it was.
+   *
+   * @param {unknown} error
+   * @param {unknown} fallback the event's own message
+   * @returns {string | null}
+   */
+  function messageOf(error, fallback) {
+    if (error instanceof Error || (typeof error === 'object' && error !== null && 'message' in error)) {
+      const { name, message } = /** @type {{ name?: unknown, message?: unknown }} */ (error);
+      const text = typeof message === 'string' ? message : '';
+      return typeof name === 'string' && name !== '' && name !== 'Error' ? `${name}: ${text}` : text;
+    }
+    if (typeof error === 'string') return error;
+    if (typeof fallback === 'string' && fallback !== '') return fallback === OPAQUE ? null : fallback;
+    return `A value that is not an error: ${error === null ? 'null' : typeof error}`;
+  }
+
+  /**
+   * The script and line a stack's first frame names.
+   *
+   * @param {string} stack
+   * @returns {{ filename: string, lineno: number } | null}
+   */
+  function frameOf(stack) {
+    for (const line of stack.split('\n')) {
+      const match = FRAME.exec(line.trim());
+      if (match) return { filename: match[1], lineno: Number(match[2]) };
+    }
+    return null;
+  }
+
+  /**
+   * A script's path when it is this origin's -- no query, no fragment --
+   * and null for any other: a third party's script, an extension's.
+   *
+   * @param {unknown} file
+   * @returns {string | null}
+   */
+  function sameOriginPath(file) {
+    if (typeof file !== 'string' || file === '') return null;
+    try {
+      const url = new URL(file, win.location.href);
+      return url.origin === win.location.origin && url.pathname.length <= 512 ? url.pathname : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * A few short frames: this origin left off its own URLs, every URL's
+   * query and fragment cut, and what a cookie holds taken out.
+   *
+   * @param {string} stack
+   */
+  function framesOf(stack) {
+    const origin = win.location.origin;
+    const lines = [];
+    for (const raw of stack.split('\n')) {
+      const line = withoutQueries(scrub(raw.trim()).split(origin).join(''));
+      if (line === '') continue;
+      lines.push(line.slice(0, MAX_STACK_LINE));
+      if (lines.length === MAX_STACK_LINES) break;
+    }
+    return lines.join('\n');
+  }
+
+  /**
+   * $text with every query and fragment cut, where a token in an address
+   * would be: an absolute URL's, and a relative or path-only one's --
+   * `/reset?token=...`, `./x#access_token=...` -- alike. A `?` or `#` in
+   * prose goes with them, which costs a message little.
+   *
+   * @param {string} text
+   */
+  function withoutQueries(text) {
+    return text.replace(/[?#][^\s():'"]*/g, '');
+  }
+
+  /**
+   * $text without anything a cookie script can read holds: a CSRF token a
+   * failed request's message quoted, say. Storage is never read at all.
+   *
+   * @param {string} text
+   */
+  function scrub(text) {
+    const cookies = typeof doc?.cookie === 'string' ? doc.cookie : '';
+    let scrubbed = text;
+    for (const pair of cookies.split(';')) {
+      const value = pair.slice(pair.indexOf('=') + 1).trim();
+      if (pair.includes('=') && value.length >= 8) scrubbed = scrubbed.split(value).join('[redacted]');
+    }
+    return scrubbed;
+  }
+
+  /** Sends what is waiting: a report per route, each within the server's caps. */
+  function flushErrors() {
+    if (timer !== null) win.clearTimeout(timer);
+    timer = null;
+    if (pending.length === 0) return;
+
+    /** @type {Map<string, Array<Record<string, unknown>>>} */
+    const byRoute = new Map();
+    for (const { route, error } of pending.splice(0)) {
+      if (!byRoute.has(route)) byRoute.set(route, []);
+      byRoute.get(route)?.push(error);
+    }
+
+    for (const [route, errors] of byRoute) {
+      for (const body of reports(route, errors)) post(ERRORS_PATH, body);
+    }
+  }
+
+  /**
+   * $errors as reports of at most MAX_ERRORS_PER_REPORT, each under
+   * MAX_BODY_BYTES as sent.
+   *
+   * @param {string} route
+   * @param {Array<Record<string, unknown>>} errors
+   */
+  function reports(route, errors) {
+    const bytes = (body) => new TextEncoder().encode(JSON.stringify(body)).length;
+    const bodies = [];
+    let current = [];
+    for (const error of errors) {
+      const next = [...current, error];
+      if (
+        current.length > 0 &&
+        (next.length > MAX_ERRORS_PER_REPORT || bytes({ route, errors: next }) > MAX_BODY_BYTES)
+      ) {
+        bodies.push({ route, errors: current });
+        current = [error];
+      } else {
+        current = next;
+      }
+    }
+    if (current.length > 0) bodies.push({ route, errors: current });
+    return bodies.filter((body) => bytes(body) <= MAX_BODY_BYTES);
+  }
+
+  /**
+   * A hook for React's root: reports, then hands the error on as React's
+   * own default would -- to the console for one a boundary caught, to the
+   * browser's error reporting otherwise -- without it being taken twice.
+   *
+   * @param {string} kind
+   * @param {(error: unknown) => void} handOn
+   */
+  function hook(kind, handOn) {
+    return (/** @type {unknown} */ error) => {
+      reportError(error, kind);
+      handingOn = error;
+      try {
+        handOn(error);
+      } finally {
+        handingOn = undefined;
+      }
+    };
+  }
+
+  const toConsole = (error) => console.error(error);
+  const toBrowser = (error) =>
+    typeof win?.reportError === 'function' ? win.reportError(error) : console.error(error);
+
+  // ---------------------------------------------------------------- lifecycle
+
+  /** @param {Window} target @param {string} name @param {(event: any) => void} fn */
+  function listen(target, name, fn) {
+    target.addEventListener(name, fn);
+    teardown.push(() => target.removeEventListener(name, fn));
+  }
+
+  function hidden() {
+    if (doc?.visibilityState === 'hidden') firstHidden = Math.min(firstHidden, win.performance?.now?.() ?? 0);
+    sendVitals();
+    flushErrors();
+    flushViolations();
+  }
+
+  const telemetry = {
+    /** Starts measuring and listening. Once; and never again after stop(). */
+    start() {
+      if (started || stopped || win === undefined || doc === undefined) return telemetry;
+      started = true;
+
+      const [token] = router?.routeTokens() ?? [];
+      const metadata = readPageMetadata(doc);
+      page.route = labelOf(metadata?.route) ?? routeNameOf(metadata?.routeToken ?? token);
+      page.interactionsBefore = 0;
+
+      if (options.vitals !== false) observeVitals();
+
+      if (options.violations !== false) {
+        const meta = doc.querySelector?.('meta[http-equiv="Content-Security-Policy" i]');
+        const content = meta?.getAttribute?.('content');
+        metaPolicy = typeof content === 'string' && content.trim() !== '' ? content.trim() : null;
+        if (metaPolicy !== null) listen(doc, 'securitypolicyviolation', violation);
+      }
+
+      if (options.errors !== false) {
+        listen(win, 'error', (event) => {
+          if (event.error !== undefined && event.error === handingOn) return;
+          reportError(event.error ?? null, 'error', event);
+        });
+        listen(win, 'unhandledrejection', (event) => reportError(event.reason, 'rejection'));
+      }
+
+      listen(doc, 'visibilitychange', () => {
+        if (doc.visibilityState === 'hidden') hidden();
+      });
+      listen(win, 'pagehide', hidden);
+
+      if (router !== null) {
+        // When the visit to the next page began, for its NAV.
+        teardown.push(
+          router.on('start', (event) => {
+            if (!event.detail?.background) visitStarted = now();
+          }),
+        );
+        // A page the router mounts is a page of its own: its errors are
+        // counted and told apart afresh, and its vitals are its own. A poll
+        // or a partial reload is the same page.
+        teardown.push(
+          router.on('success', (event) => {
+            if (event.detail?.background || event.detail?.partial) return;
+            seen = new Set();
+            reportedHere = 0;
+            if (options.vitals !== false && !stopped) mounted();
+            else page = { ...page, route: mountedRoute() };
+          }),
+        );
+        // The session has ended here: nothing more is sent under it.
+        teardown.push(
+          router.on('revoke', () => {
+            revoked = true;
+            pending = [];
+            violations = [];
+          }),
+        );
+      }
+
+      return telemetry;
+    },
+
+    /** Stops listening and measuring, sending nothing more. */
+    stop() {
+      stopped = true;
+      for (const undo of teardown.splice(0)) undo();
+      for (const [observer] of observers.splice(0)) observer.disconnect();
+      if (timer !== null) win.clearTimeout(timer);
+      timer = null;
+      pending = [];
+      if (violationTimer !== null) win.clearTimeout(violationTimer);
+      violationTimer = null;
+      violations = [];
+    },
+
+    reportError: (/** @type {unknown} */ error, /** @type {string} */ kind = 'error') =>
+      reportError(error, kind),
+
+    /** For hydrateRoot()'s options: an error a boundary caught. */
+    onCaughtError: hook('caught', toConsole),
+
+    /** For hydrateRoot()'s options: an error no boundary caught. */
+    onUncaughtError: hook('uncaught', toBrowser),
+
+    /** For hydrateRoot()'s options: an error React recovered from, such as a hydration mismatch. */
+    onRecoverableError: hook('recoverable', toBrowser),
+
+    /** Sends the errors waiting now, rather than in a moment. */
+    flush: flushErrors,
+
+    vitals,
+  };
+
+  return telemetry;
+}