midline-agent 0.3.0 → 0.4.0

package/src/browser/client.ts

@@ -0,0 +1,686 @@
+import { Redactor } from "../redact.js";
+import type { Breadcrumb, EventCategory, EventSeverity } from "../types.js";
+import {
+  ErrorLocation,
+  InstrumentHooks,
+  Propagation,
+  RequestRecord,
+  instrumentConsole,
+  instrumentErrors,
+  instrumentFetch,
+  instrumentHistory,
+  instrumentXhr,
+} from "./instrument.js";
+import { BrowserTransport } from "./transport.js";
+import type {
+  BrowserEvent,
+  CaptureContext,
+  ConsoleLevel,
+  MidlineBrowserConfig,
+  MidlineUser,
+  RequestCapture,
+} from "./types.js";
+import { BROWSER_SDK_VERSION } from "./version.js";
+import { observeVitals, VitalsReport } from "./vitals.js";
+
+/** Same default as the Node agent (src/config.ts), repeated so this bundle stays free of Node code. */
+const DEFAULT_ENDPOINT = "https://api.usemidline.com";
+const INGEST_PATH = "/api/api-monitor/events";
+
+const MAX_BREADCRUMBS = 50;
+const MAX_EVENT_CHARS = 60_000;
+const DUPLICATE_WINDOW_MS = 5_000;
+/** Matches the Node agent's console line cap. */
+const MAX_CONSOLE_CHARS = 4096;
+
+const CONSOLE_SEVERITY: Record<ConsoleLevel, EventSeverity> = {
+  error: "high",
+  warn: "medium",
+  info: "low",
+  log: "low",
+  debug: "low",
+};
+
+/** Top-level fields the ingest API accepts from this SDK; it rejects the whole batch on anything else. */
+const WIRE_FIELDS = new Set<string>([
+  "eventType", "route", "method", "statusCode", "responseTime", "severity", "category", "timestamp",
+  "service", "environment", "release", "userAgent", "traceId", "spanId", "payload", "metadata",
+]);
+
+interface Resolved {
+  apiKey: string;
+  batchUrl: string;
+  ingestPrefix: string;
+  service?: string;
+  environment?: string;
+  release?: string;
+  captureErrors: boolean;
+  captureRequests: RequestCapture;
+  consoleLevels: ConsoleLevel[];
+  captureWebVitals: boolean;
+  tracePropagationTargets?: Array<string | RegExp>;
+  ignoreErrors: Array<string | RegExp>;
+  ignoreUrls: Array<string | RegExp>;
+  sampleRate: number;
+  maxEventsPerMinute: number;
+  beforeSend?: MidlineBrowserConfig["beforeSend"];
+  debug: boolean;
+  flushIntervalMs: number;
+  maxBatchSize: number;
+  maxQueueSize: number;
+}
+
+export class BrowserConfigError extends Error {}
+
+/** Accepts a base URL or the ingest URL, and returns the batch URL. */
+export function resolveBatchUrl(endpoint: string = DEFAULT_ENDPOINT): string {
+  let url: URL;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    throw new BrowserConfigError(`endpoint "${endpoint}" is not a valid URL`);
+  }
+  if (url.username || url.password) {
+    throw new BrowserConfigError("endpoint must not contain credentials");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new BrowserConfigError(`endpoint must use https:// (http:// is only allowed for localhost)`);
+  }
+  let path = url.pathname.replace(/\/+$/, "");
+  if (path.endsWith(`${INGEST_PATH}/batch`)) {
+    // already the batch URL
+  } else if (path.endsWith(INGEST_PATH)) {
+    path += "/batch";
+  } else {
+    path += `${INGEST_PATH}/batch`;
+  }
+  return `${url.origin}${path}`;
+}
+
+function resolve(config: MidlineBrowserConfig): Resolved {
+  const apiKey = typeof config.apiKey === "string" ? config.apiKey.trim() : "";
+  if (!apiKey) {
+    throw new BrowserConfigError("apiKey is required: create a browser key (pk_…) in the Midline dashboard");
+  }
+  if (apiKey.startsWith("ak_")) {
+    throw new BrowserConfigError(
+      "this is a server key (ak_…). Server keys are secrets: anyone can read a key shipped to a browser, " +
+        "and the Midline server refuses them from browsers. Create a browser key (pk_…) for this app.",
+    );
+  }
+  const batchUrl = resolveBatchUrl(config.endpoint);
+  const levels: ConsoleLevel[] =
+    config.captureConsole === true ? ["error", "warn"] : Array.isArray(config.captureConsole) ? config.captureConsole : [];
+
+  return {
+    apiKey,
+    batchUrl,
+    ingestPrefix: batchUrl.slice(0, batchUrl.length - "/batch".length),
+    service: clamp(config.service, 128),
+    environment: clamp(config.environment, 128),
+    release: clamp(config.release, 128),
+    captureErrors: config.captureErrors !== false,
+    captureRequests: config.captureRequests === undefined ? "failed" : config.captureRequests,
+    consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
+    captureWebVitals: config.captureWebVitals !== false,
+    tracePropagationTargets: config.tracePropagationTargets,
+    ignoreErrors: config.ignoreErrors ?? [],
+    ignoreUrls: config.ignoreUrls ?? [],
+    sampleRate: clampNumber(config.sampleRate, 0, 1, 1),
+    maxEventsPerMinute: clampNumber(config.maxEventsPerMinute, 1, 10_000, 120),
+    beforeSend: config.beforeSend,
+    debug: config.debug === true,
+    flushIntervalMs: clampNumber(config.flushIntervalMs, 250, 60_000, 5000),
+    maxBatchSize: Math.round(clampNumber(config.maxBatchSize, 1, 100, 20)),
+    maxQueueSize: Math.round(clampNumber(config.maxQueueSize, 1, 5000, 200)),
+  };
+}
+
+/**
+ * One installed SDK instance. Everything it does to the page — wrapped fetch,
+ * XHR, console and history, window listeners — is undone by `close()`.
+ */
+export class BrowserClient {
+  private readonly redactor: Redactor;
+  private readonly transport: BrowserTransport;
+  private readonly teardowns: Array<() => void> = [];
+  private readonly breadcrumbs: Breadcrumb[] = [];
+  private readonly recentErrors = new Map<string, number>();
+  private readonly sessionId = sessionIdFor();
+  private readonly originalConsole: Pick<Console, "warn" | "log">;
+  private traceId = randomHex(16);
+  private user: MidlineUser | undefined;
+  private tags: Record<string, string> = {};
+  private tokens: number;
+  private lastRefill = Date.now();
+  private active = true;
+  private inConsoleHook = false;
+  private rateLimitNoted = false;
+
+  private constructor(
+    private readonly win: Window,
+    private readonly config: Resolved,
+    redactFields: string[],
+  ) {
+    this.redactor = new Redactor(redactFields);
+    this.tokens = config.maxEventsPerMinute;
+    const console = consoleOf(win);
+    this.originalConsole = { warn: console.warn.bind(console), log: console.log.bind(console) };
+
+    const originalFetch = win.fetch;
+    this.transport = new BrowserTransport({
+      batchUrl: config.batchUrl,
+      apiKey: config.apiKey,
+      // Called with the window as `this`: a detached fetch throws "Illegal invocation".
+      fetch: (input, init) => originalFetch.call(win, input, init),
+      flushIntervalMs: config.flushIntervalMs,
+      maxBatchSize: config.maxBatchSize,
+      maxQueueSize: config.maxQueueSize,
+      debug: (message) => this.debug(message),
+      onStop: (message) => {
+        this.active = false;
+        this.originalConsole.warn(message);
+      },
+    });
+    this.install(originalFetch);
+  }
+
+  /** Returns undefined, after one console warning, when the SDK can't run. It never throws into the app. */
+  static create(config: MidlineBrowserConfig): BrowserClient | undefined {
+    const win = typeof window === "undefined" ? undefined : window;
+    if (!win || typeof win.fetch !== "function") {
+      // Server-side rendering, a worker, or a browser too old to matter.
+      return undefined;
+    }
+    if (config?.enabled === false) return undefined;
+    try {
+      return new BrowserClient(win, resolve(config), config.redactFields ?? []);
+    } catch (error) {
+      consoleOf(win)?.warn?.(`midline: browser monitoring is off — ${error instanceof Error ? error.message : String(error)}`);
+      return undefined;
+    }
+  }
+
+  private install(originalFetch: typeof fetch): void {
+    const hooks: InstrumentHooks = {
+      onError: (error, mechanism, location) => this.handleError(error, mechanism, location),
+      onRequest: (record) => this.handleRequest(record),
+      onConsole: (level, args) => this.handleConsole(level, args),
+      onNavigation: (from, to) => this.handleNavigation(from, to),
+      propagation: (url) => this.propagation(url),
+      isOwnRequest: (url) => url.href.startsWith(this.config.ingestPrefix),
+    };
+
+    if (this.config.captureErrors) this.teardowns.push(instrumentErrors(this.win, hooks));
+    this.teardowns.push(instrumentFetch(this.win, originalFetch, hooks));
+    this.teardowns.push(instrumentXhr(this.win, hooks));
+    this.teardowns.push(instrumentHistory(this.win, hooks));
+    if (this.config.consoleLevels.length) {
+      this.teardowns.push(instrumentConsole(consoleOf(this.win), this.config.consoleLevels, hooks));
+    }
+    if (this.config.captureWebVitals) {
+      this.teardowns.push(observeVitals(this.win, (report) => this.handleVitals(report)));
+    }
+
+    // Registered after the vitals listener so its event is queued before this sends.
+    const onHide = () => {
+      if (this.win.document?.visibilityState === "hidden") this.transport.flushOnHide();
+    };
+    const onPageHide = () => this.transport.flushOnHide();
+    this.win.document?.addEventListener("visibilitychange", onHide, true);
+    this.win.addEventListener("pagehide", onPageHide, true);
+    this.teardowns.push(() => {
+      this.win.document?.removeEventListener("visibilitychange", onHide, true);
+      this.win.removeEventListener("pagehide", onPageHide, true);
+    });
+
+    this.transport.start();
+    this.debug(`midline: browser monitoring on, sending to ${this.config.batchUrl}`);
+  }
+
+  // ---- public API -------------------------------------------------------------
+
+  captureException(error: unknown, context?: CaptureContext): void {
+    this.guard(() => this.handleError(error, "manual", undefined, context));
+  }
+
+  captureMessage(message: string, severity: EventSeverity = "low", context?: CaptureContext): void {
+    this.guard(() => {
+      const event = this.base("custom", this.currentRoute(), severity, "application");
+      event.payload = {
+        message: this.redactor.string(String(message), 1024),
+        ...this.contextPayload(context),
+      };
+      this.applyTags(event, context);
+      this.emit(event);
+    });
+  }
+
+  setUser(user: MidlineUser | null): void {
+    this.user = user
+      ? {
+          id: user.id === undefined ? undefined : String(user.id).slice(0, 128),
+          username: user.username === undefined ? undefined : String(user.username).slice(0, 128),
+        }
+      : undefined;
+  }
+
+  setTag(key: string, value: string): void {
+    if (Object.keys(this.tags).length >= 50 && !(key in this.tags)) return;
+    this.tags[String(key).slice(0, 64)] = String(value).slice(0, 256);
+  }
+
+  addBreadcrumb(message: string, type = "manual"): void {
+    this.guard(() => this.breadcrumb(type, message));
+  }
+
+  flush(): Promise<void> {
+    return this.transport.flush().catch(() => undefined);
+  }
+
+  async close(): Promise<void> {
+    for (const teardown of this.teardowns.splice(0).reverse()) {
+      try {
+        teardown();
+      } catch {
+        // keep tearing down the rest
+      }
+    }
+    await this.flush();
+    this.active = false;
+    this.transport.stop();
+  }
+
+  // ---- event sources ----------------------------------------------------------
+
+  private handleError(
+    error: unknown,
+    mechanism: "onerror" | "unhandledrejection" | "manual",
+    location?: ErrorLocation,
+    context?: CaptureContext,
+  ): void {
+    const { name, message, stack } = describeError(error, location);
+    // A script from another origin without CORS headers reports only this. There
+    // is nothing to act on, and it would otherwise group every such error into one.
+    if (message === "Script error." && !stack) {
+      this.debug("midline: skipped a cross-origin \"Script error.\" (add crossorigin to the script tag to see it)");
+      return;
+    }
+    if (matches(message, this.config.ignoreErrors)) return;
+
+    const signature = `${message}\n${(stack ?? "").slice(0, 500)}`;
+    const now = Date.now();
+    const seenAt = this.recentErrors.get(signature);
+    if (mechanism !== "manual" && seenAt !== undefined && now - seenAt < DUPLICATE_WINDOW_MS) return;
+    this.recentErrors.set(signature, now);
+    if (this.recentErrors.size > 100) {
+      this.recentErrors.delete(this.recentErrors.keys().next().value as string);
+    }
+
+    const event = this.base("error", this.currentRoute(), "high", "application");
+    event.payload = {
+      error: this.redactor.string(message, 1024),
+      type: name,
+      stack: stack ? this.redactor.string(stack, 16 * 1024) : undefined,
+      mechanism,
+      breadcrumbs: this.breadcrumbs.slice(-20),
+      context: {
+        url: this.pageUrl(),
+        filename: location?.filename ? this.redactor.string(stripQuery(location.filename), 1024) : undefined,
+        line: location?.lineno || undefined,
+        column: location?.colno || undefined,
+      },
+      ...this.contextPayload(context),
+    };
+    this.applyTags(event, context);
+    this.emit(event);
+    this.breadcrumb("error", `${name}: ${message}`);
+  }
+
+  private handleRequest(record: RequestRecord): void {
+    const { url } = record;
+    const sameOrigin = url.origin === this.win.location.origin;
+    const target = sameOrigin ? url.pathname : `${url.origin}${url.pathname}`;
+    const outcome = record.status ?? (record.aborted ? "aborted" : "failed");
+    this.breadcrumb(record.kind, `${record.method} ${target} ${outcome}`);
+
+    if (record.aborted || matches(url.href, this.config.ignoreUrls)) return;
+    const networkError = record.status === undefined;
+    const failed = networkError || record.status! >= 400;
+    if (this.config.captureRequests === false || (this.config.captureRequests === "failed" && !failed)) return;
+
+    const severity: EventSeverity = networkError || record.status! >= 500 ? "high" : record.status! >= 400 ? "medium" : "low";
+    const event = this.base(
+      networkError ? "error" : "request",
+      url.pathname,
+      severity,
+      networkError ? "infrastructure" : "application",
+    );
+    event.method = record.method.slice(0, 16);
+    if (!networkError && record.status! >= 100 && record.status! <= 599) event.statusCode = record.status;
+    event.responseTime = Math.min(Math.max(0, Math.round(record.durationMs)), 86_400_000);
+    event.spanId = record.spanId;
+    event.payload = {
+      request: {
+        url: this.redactor.string(`${url.origin}${url.pathname}`, 2048),
+        query: url.search ? this.redactor.query(url.search) : undefined,
+        crossOrigin: !sameOrigin,
+        via: record.kind,
+      },
+      ...(networkError
+        ? {
+            error: `Network request failed: ${record.method} ${this.redactor.string(target, 512)}`,
+            code: "NETWORK_ERROR",
+            breadcrumbs: this.breadcrumbs.slice(-20),
+          }
+        : {}),
+    };
+    this.emit(event);
+  }
+
+  private handleConsole(level: ConsoleLevel, args: unknown[]): void {
+    // Anything this SDK prints must not loop back in as an event.
+    if (this.inConsoleHook) return;
+    this.inConsoleHook = true;
+    try {
+      const line = formatConsoleArgs(args);
+      this.breadcrumb("console", `[${level}] ${line.slice(0, 256)}`);
+      const event = this.base("console", this.currentRoute(), CONSOLE_SEVERITY[level]);
+      event.payload = { message: this.redactor.string(line, MAX_CONSOLE_CHARS) };
+      event.metadata.level = level;
+      this.emit(event);
+    } finally {
+      this.inConsoleHook = false;
+    }
+  }
+
+  private handleNavigation(from: string, to: string): void {
+    // A new view is a new trace, so its API calls don't blur into the last one's.
+    this.traceId = randomHex(16);
+    this.breadcrumb("navigation", `${pathOf(from)} -> ${pathOf(to)}`);
+  }
+
+  private handleVitals(report: VitalsReport): void {
+    const poor = Object.values(report.vitals).some((vital) => vital?.rating === "poor");
+    const event = this.base("performance", this.currentRoute(), poor ? "medium" : "low", "performance");
+    event.payload = { vitals: report.vitals, navigationType: report.navigationType };
+    this.emit(event);
+  }
+
+  // ---- plumbing -----------------------------------------------------------------
+
+  private propagation(url: URL): Propagation | undefined {
+    const targets = this.config.tracePropagationTargets;
+    const pageOrigin = this.win.location.origin;
+    const allowed = targets
+      ? targets.some((target) =>
+          typeof target === "string"
+            ? target.startsWith("/")
+              ? url.origin === pageOrigin && url.pathname.startsWith(target)
+              : url.href.startsWith(target)
+            : safeTest(target, url.href),
+        )
+      : url.origin === pageOrigin;
+    if (!allowed) return undefined;
+    const spanId = randomHex(8);
+    return { headers: { traceparent: `00-${this.traceId}-${spanId}-01` }, spanId };
+  }
+
+  private base(
+    eventType: BrowserEvent["eventType"],
+    route: string,
+    severity: EventSeverity,
+    category?: EventCategory,
+  ): BrowserEvent {
+    const metadata: Record<string, unknown> = {
+      source: "sdk",
+      sdk: "midline-agent/browser",
+      version: BROWSER_SDK_VERSION,
+      runtime: "browser",
+      sessionId: this.sessionId,
+      page: { url: this.pageUrl(), path: this.currentRoute() },
+    };
+    if (this.user && (this.user.id || this.user.username)) metadata.user = { ...this.user };
+    if (Object.keys(this.tags).length) metadata.tags = { ...this.tags };
+    const nav = this.win.navigator;
+
+    return {
+      eventType,
+      route: this.redactor.string(route || "/", 2048),
+      severity,
+      category,
+      timestamp: new Date().toISOString(),
+      service: this.config.service,
+      environment: this.config.environment,
+      release: this.config.release,
+      userAgent: clamp(nav?.userAgent, 512),
+      traceId: this.traceId,
+      metadata,
+    };
+  }
+
+  private emit(event: BrowserEvent): void {
+    if (!this.active) return;
+    if (this.config.sampleRate < 1 && Math.random() >= this.config.sampleRate) return;
+    if (!this.takeToken()) {
+      if (!this.rateLimitNoted) {
+        this.rateLimitNoted = true;
+        this.debug(`midline: over ${this.config.maxEventsPerMinute} events a minute; dropping until it calms down.`);
+      }
+      return;
+    }
+
+    let final: BrowserEvent | null | undefined = event;
+    if (this.config.beforeSend) {
+      try {
+        final = this.config.beforeSend(event);
+      } catch (error) {
+        this.debug(`midline: beforeSend threw (${error instanceof Error ? error.message : String(error)}); sending the event unchanged.`);
+        final = event;
+      }
+      if (!final) return;
+    }
+
+    const wire = toWire(final);
+    if (!wire) {
+      this.debug("midline: dropped an event larger than 60 KB.");
+      return;
+    }
+    this.transport.enqueue(wire);
+  }
+
+  private takeToken(): boolean {
+    const now = Date.now();
+    const perMs = this.config.maxEventsPerMinute / 60_000;
+    this.tokens = Math.min(this.config.maxEventsPerMinute, this.tokens + (now - this.lastRefill) * perMs);
+    this.lastRefill = now;
+    if (this.tokens < 1) return false;
+    this.tokens -= 1;
+    this.rateLimitNoted = false;
+    return true;
+  }
+
+  private breadcrumb(type: string, message: string): void {
+    this.breadcrumbs.push({
+      type: type.slice(0, 32),
+      message: this.redactor.string(String(message), 256),
+      timestamp: new Date().toISOString(),
+    });
+    if (this.breadcrumbs.length > MAX_BREADCRUMBS) this.breadcrumbs.shift();
+  }
+
+  private contextPayload(context?: CaptureContext): Record<string, unknown> {
+    return context?.extra ? { extra: this.redactor.value(context.extra) } : {};
+  }
+
+  private applyTags(event: BrowserEvent, context?: CaptureContext): void {
+    if (!context?.tags) return;
+    const tags: Record<string, string> = { ...((event.metadata.tags as Record<string, string>) ?? {}) };
+    for (const [key, value] of Object.entries(context.tags).slice(0, 50)) {
+      tags[String(key).slice(0, 64)] = String(value).slice(0, 256);
+    }
+    event.metadata.tags = tags;
+  }
+
+  /** The page path, plus a `#/…` hash route when the app routes by hash. Never the query string. */
+  private currentRoute(): string {
+    const { pathname, hash } = this.win.location;
+    return hash.startsWith("#/") ? `${pathname}${hash.split("?")[0]}` : pathname || "/";
+  }
+
+  private pageUrl(): string {
+    const { origin, pathname } = this.win.location;
+    return this.redactor.string(`${origin}${pathname}`, 2048);
+  }
+
+  private guard(fn: () => void): void {
+    try {
+      fn();
+    } catch (error) {
+      this.debug(`midline: internal error (${error instanceof Error ? error.message : String(error)})`);
+    }
+  }
+
+  private debug(message: string): void {
+    if (this.config.debug) this.originalConsole.log(message);
+  }
+}
+
+/** The DOM typings declare console as a global, not a Window property. */
+function consoleOf(win: Window): Console {
+  return (win as Window & { console: Console }).console;
+}
+
+/** Removes empty fields and anything the ingest API would refuse; trims oversized events. */
+function toWire(event: BrowserEvent): BrowserEvent | undefined {
+  const wire: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(event)) {
+    if (value !== undefined && WIRE_FIELDS.has(key)) wire[key] = value;
+  }
+  const payload = wire.payload as Record<string, unknown> | undefined;
+  if (payload) {
+    for (const key of Object.keys(payload)) {
+      if (payload[key] === undefined) delete payload[key];
+    }
+  }
+
+  const size = () => {
+    try {
+      return JSON.stringify(wire).length;
+    } catch {
+      return Infinity;
+    }
+  };
+  if (size() > MAX_EVENT_CHARS && payload) {
+    delete payload.breadcrumbs;
+    if (typeof payload.stack === "string") payload.stack = payload.stack.slice(0, 2048);
+    if (size() > MAX_EVENT_CHARS) delete payload.extra;
+  }
+  return size() > MAX_EVENT_CHARS ? undefined : (wire as unknown as BrowserEvent);
+}
+
+function describeError(error: unknown, location?: ErrorLocation): { name: string; message: string; stack?: string } {
+  if (error instanceof Error || (typeof error === "object" && error !== null && "message" in error)) {
+    const e = error as Error;
+    return {
+      name: typeof e.name === "string" && e.name ? e.name.slice(0, 128) : "Error",
+      message: String(e.message ?? "") || location?.message || "Unknown error",
+      stack: typeof e.stack === "string" ? e.stack : undefined,
+    };
+  }
+  if (typeof error === "string") {
+    return { name: "Error", message: error || location?.message || "Unknown error" };
+  }
+  if (error === undefined || error === null) {
+    return { name: "Error", message: location?.message || "Unknown error" };
+  }
+  let text: string;
+  try {
+    text = JSON.stringify(error) ?? String(error);
+  } catch {
+    text = Object.prototype.toString.call(error);
+  }
+  return { name: "Error", message: `Non-Error value thrown: ${text.slice(0, 512)}` };
+}
+
+function formatConsoleArgs(args: unknown[]): string {
+  const parts: string[] = [];
+  let length = 0;
+  for (const arg of args) {
+    let text: string;
+    if (typeof arg === "string") text = arg;
+    else if (arg instanceof Error) text = arg.stack || `${arg.name}: ${arg.message}`;
+    else {
+      try {
+        text = typeof arg === "object" && arg !== null ? JSON.stringify(arg) ?? String(arg) : String(arg);
+      } catch {
+        text = Object.prototype.toString.call(arg);
+      }
+    }
+    parts.push(text);
+    length += text.length + 1;
+    if (length > MAX_CONSOLE_CHARS * 2) break;
+  }
+  return parts.join(" ");
+}
+
+function matches(value: string, patterns: Array<string | RegExp>): boolean {
+  return patterns.some((pattern) => (typeof pattern === "string" ? value.includes(pattern) : safeTest(pattern, value)));
+}
+
+function safeTest(pattern: RegExp, value: string): boolean {
+  pattern.lastIndex = 0;
+  return pattern.test(value);
+}
+
+function stripQuery(url: string): string {
+  return url.split(/[?#]/)[0];
+}
+
+function pathOf(href: string): string {
+  try {
+    const url = new URL(href);
+    return url.hash.startsWith("#/") ? `${url.pathname}${url.hash.split("?")[0]}` : url.pathname;
+  } catch {
+    return "";
+  }
+}
+
+function clamp(value: unknown, max: number): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  return String(value).slice(0, max);
+}
+
+function clampNumber(value: unknown, min: number, max: number, fallback: number): number {
+  const n = typeof value === "number" ? value : NaN;
+  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
+}
+
+/** W3C ids: lowercase hex, never all zeros. */
+export function randomHex(bytes: number): string {
+  const buffer = new Uint8Array(bytes);
+  const crypto = (globalThis as { crypto?: Crypto }).crypto;
+  if (crypto && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(buffer);
+  } else {
+    for (let i = 0; i < bytes; i++) buffer[i] = Math.floor(Math.random() * 256);
+  }
+  let hex = "";
+  for (const byte of buffer) hex += byte.toString(16).padStart(2, "0");
+  return /^0+$/.test(hex) ? randomHex(bytes) : hex;
+}
+
+/** Stable for the tab's lifetime; sessionStorage can be unavailable (privacy modes, sandboxed frames). */
+function sessionIdFor(): string {
+  try {
+    const storage = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+    const existing = storage?.getItem("midline.sid");
+    if (existing && /^[a-f0-9]{16,64}$/.test(existing)) return existing;
+    const id = randomHex(16);
+    storage?.setItem("midline.sid", id);
+    return id;
+  } catch {
+    return randomHex(16);
+  }
+}