@devaccel-labs/app-comments-toolbar 1.0.0 → 1.3.0

package/src/runtime/debug-context.ts

@@ -0,0 +1,613 @@
+/**
+ * Debug context on a web page: the hooks (console, `error`, `unhandledrejection`, fetch, XHR, resources,
+ * CSP, online, visibility, performance) that feed the shared core (`./debug-context-core.ts`), and what
+ * only a page has: its address, the browser, the element pointed at, storage.
+ *
+ * Runs only while someone is signed in to the toolbar and the host turned debug context on in code. Nothing
+ * leaves the page until a report is posted.
+ */
+import type { Anchor } from "../core/index.js";
+import { browserName, systemName } from "./browser-label.js";
+import { runtimeBuild } from "./build-id.js";
+import {
+  BODY_CHARS,
+  createDebugCore,
+  errorOf,
+  excerptOf,
+  FOREIGN_FRAME,
+  GRAPHQL_READ_CHARS,
+  patch,
+  within,
+  type DebugCaptureStats,
+} from "./debug-context-core.js";
+import type { DebugContextFile, ResolvedDebugContext } from "./debug-context-model.js";
+import { newTally, scrubText, scrubUrl, type RedactionTally } from "./debug-context-redact.js";
+import type { ReplayEvent } from "./replay-model.js";
+
+export type { DebugCaptureStats } from "./debug-context-core.js";
+
+export type DebugSnapshotInput = {
+  element?: Element | null;
+  anchor?: Anchor | null;
+  /** The toolbar's step trail (its replay buffer), oldest first. */
+  steps?: readonly ReplayEvent[];
+};
+
+export type DebugCapture = {
+  /** The moment the person started the report: the file's clock and the "still pending" list come from it. */
+  mark(): void;
+  /** The file, redacted and bounded, or null when the host's `beforeCapture` refused it or threw. */
+  snapshot(input?: DebugSnapshotInput): Promise<DebugContextFile | null>;
+  /** An error the host's error boundary caught (`componentStacks`). */
+  reportError(error: unknown, componentStack?: string | null): void;
+  /** Time spent in this module's hooks, for measuring the hot path. */
+  stats(): DebugCaptureStats;
+  stop(): void;
+};
+
+export type DebugCaptureEnv = {
+  /** Requests that are the toolbar's own (the comment service): never recorded. */
+  ignoreUrl?: (url: string) => boolean;
+  window?: Window & typeof globalThis;
+};
+
+/** The text of a body as far as `max` characters, without reading the rest. */
+async function readCapped(response: Response, max: number): Promise<string> {
+  const reader = response.body?.getReader();
+  if (!reader) return "";
+  const decoder = new TextDecoder();
+  let text = "";
+  let complete = false;
+  try {
+    while (text.length < max) {
+      const { done, value } = await reader.read();
+      if (done) {
+        complete = true;
+        break;
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    if (!complete) void reader.cancel().catch(() => undefined);
+  }
+  return text.slice(0, max);
+}
+
+const SKELETON_ATTRS =
+  /^(?:id|class|role|type|name|for|tabindex|disabled|hidden|href|src|data-testid|data-test|data-cs-cmp|data-cs-file|aria-[a-z-]+)$/;
+const SKIPPED_TAGS = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE"]);
+
+/**
+ * The element as HTML with its structure and the attributes that identify things, and none of its text or
+ * values: each text run becomes `[text:N]`. `data-cs-private` subtrees are left out.
+ */
+function skeleton(element: Element, budget: number, base: string, tally: RedactionTally): string {
+  let out = "";
+  const visit = (node: Element, depth: number) => {
+    if (out.length > budget) return;
+    const tag = node.tagName.toLowerCase();
+    if (SKIPPED_TAGS.has(node.tagName)) return;
+    const attrs: string[] = [];
+    for (const attr of [...node.attributes].slice(0, 20)) {
+      if (!SKELETON_ATTRS.test(attr.name)) continue;
+      const value =
+        attr.name === "href" || attr.name === "src"
+          ? scrubUrl(attr.value, 160, base, tally)
+          : scrubText(attr.value, 120, tally);
+      attrs.push(`${attr.name}="${value.replace(/"/g, "&quot;")}"`);
+    }
+    const open = `<${tag}${attrs.length ? ` ${attrs.join(" ")}` : ""}`;
+    if (node.hasAttribute("data-cs-private") || tag === "svg" || depth > 6) {
+      out += `${open} />`;
+      return;
+    }
+    out += `${open}>`;
+    let children = 0;
+    for (const child of node.childNodes) {
+      if (children++ > 20 || out.length > budget) {
+        out += "…";
+        break;
+      }
+      if (child.nodeType === 3) {
+        const length = (child.textContent ?? "").trim().length;
+        if (length) out += `[text:${length}]`;
+      } else if (child.nodeType === 1) visit(child as Element, depth + 1);
+    }
+    out += `</${tag}>`;
+  };
+  visit(element, 0);
+  return out.length > budget ? `${out.slice(0, budget)}…` : out;
+}
+
+const STYLE_NAMES = [
+  "display",
+  "visibility",
+  "position",
+  "z-index",
+  "overflow",
+  "opacity",
+  "pointer-events",
+  "transform",
+  "width",
+  "height",
+];
+
+export function startDebugContext(
+  resolved: ResolvedDebugContext,
+  env: DebugCaptureEnv = {},
+): DebugCapture {
+  const win = env.window ?? window;
+  const ignoreUrl = env.ignoreUrl ?? (() => false);
+  const core = createDebugCore(resolved, {
+    pageUrl: () => win.location.href,
+    ignoreUrl,
+    clock: () => win.performance.now(),
+  });
+  const { signals, options, timed } = core;
+  const restores: Array<() => void> = [];
+  const listeners: Array<() => void> = [];
+  const perf = { longTasks: 0, longestTaskMs: 0, inpMs: 0, lcpMs: 0, cls: 0 };
+
+  // ------------------------------------------------------------ console
+  const consoleObject = win.console;
+  const levels: Array<"error" | "warn" | "log" | "info" | "debug"> = [];
+  if (signals.errors) levels.push("error", "warn");
+  if (signals.consoleLog) levels.push("log", "info", "debug");
+  for (const level of levels) {
+    const original = consoleObject[level];
+    if (typeof original !== "function") continue;
+    const wrapped = function (this: unknown, ...args: unknown[]) {
+      if (!core.stopped) timed(() => core.consoleCall(level, args));
+      return original.apply(this ?? consoleObject, args);
+    };
+    restores.push(patch(consoleObject, level, wrapped as Console[typeof level]));
+  }
+
+  const listen = <K extends keyof WindowEventMap>(
+    type: K,
+    handler: (event: WindowEventMap[K]) => void,
+    capture = false,
+  ) => {
+    const wrapped = (event: WindowEventMap[K]) => timed(() => handler(event));
+    win.addEventListener(type, wrapped as EventListener, capture);
+    listeners.push(() => win.removeEventListener(type, wrapped as EventListener, capture));
+  };
+  const listenDocument = <K extends keyof DocumentEventMap>(
+    type: K,
+    handler: (event: DocumentEventMap[K]) => void,
+  ) => {
+    const wrapped = (event: DocumentEventMap[K]) => timed(() => handler(event));
+    win.document.addEventListener(type, wrapped as EventListener);
+    listeners.push(() => win.document.removeEventListener(type, wrapped as EventListener));
+  };
+
+  // ------------------------------------------------------------ errors, resources, CSP
+  if (signals.errors || signals.resources) {
+    listen(
+      "error",
+      (event) => {
+        const target = event.target;
+        if (target && target !== win && typeof (target as Element).tagName === "string") {
+          if (!signals.resources) return;
+          const element = target as HTMLElement & { src?: string; href?: string };
+          const url = element.src || element.href || "";
+          if (!url || ignoreUrl(url)) return;
+          core.pushError(
+            "resource",
+            "error",
+            `Failed to load <${element.tagName.toLowerCase()}> ${scrubUrl(url, 300, win.location.href, core.tally)}`,
+          );
+          return;
+        }
+        if (!signals.errors) return;
+        const { message, stack } =
+          event.error !== undefined && event.error !== null
+            ? errorOf(event.error)
+            : { message: event.message, stack: undefined };
+        const source = event.filename
+          ? `${event.filename}:${event.lineno}:${event.colno}`
+          : undefined;
+        if (source && FOREIGN_FRAME.test(source)) return;
+        if (!stack && /^Script error\.?$/.test(message || "")) return;
+        core.pushError("uncaught", "error", message || "error", stack, source);
+      },
+      true,
+    );
+  }
+  if (signals.errors) {
+    listen("unhandledrejection", (event) => {
+      const reason = event.reason as unknown;
+      if (reason instanceof DOMException && reason.name === "AbortError") return;
+      const { message, stack } = errorOf(reason);
+      core.pushError("rejection", "error", message, stack);
+    });
+  }
+  if (signals.resources) {
+    listenDocument("securitypolicyviolation", (event) => {
+      if (ignoreUrl(event.blockedURI)) return;
+      const blocked = event.blockedURI
+        ? scrubUrl(event.blockedURI, 200, win.location.href, core.tally)
+        : "inline";
+      core.pushError(
+        "csp",
+        "error",
+        `CSP blocked ${blocked} (${event.effectiveDirective || event.violatedDirective})`,
+        undefined,
+        event.sourceFile
+          ? `${event.sourceFile}:${event.lineNumber}:${event.columnNumber}`
+          : undefined,
+      );
+    });
+  }
+
+  // ------------------------------------------------------------ lifecycle
+  if (signals.lifecycle) {
+    listen("online", () => core.noteLifecycle("online"));
+    listen("offline", () => core.noteLifecycle("offline"));
+    listenDocument("visibilitychange", () =>
+      core.noteLifecycle(win.document.visibilityState === "hidden" ? "hidden" : "visible"),
+    );
+  }
+
+  // ------------------------------------------------------------ network
+  if (signals.network) {
+    const host = win as unknown as { fetch?: typeof fetch };
+    const originalFetch = host.fetch;
+    if (typeof originalFetch === "function") {
+      const wrappedFetch = function (this: unknown, input: RequestInfo | URL, init?: RequestInit) {
+        if (core.stopped) return originalFetch.call(win, input, init);
+        const url =
+          typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const id = timed(() => {
+          const method =
+            init?.method ?? (typeof input === "object" && "method" in input ? input.method : "GET");
+          return core.requestStarted(method, url);
+        });
+        const call = originalFetch.call(win, input, init) as Promise<Response>;
+        if (id === null) return call;
+        return call.then(
+          (response) => {
+            timed(() => {
+              const failed = response.status >= 400;
+              // A copy is made only when its text may be read: a failed response, or a GraphQL answer that
+              // may hold errors behind a 200. It has to exist before the app reads the body.
+              let copy: Response | null = null;
+              if (
+                (failed && (signals.responseExcerpts || signals.bodies)) ||
+                (!failed && /graphql/i.test(url))
+              ) {
+                try {
+                  copy = response.clone();
+                } catch {
+                  copy = null;
+                }
+              }
+              // One read of the one copy, however often it is asked for: an unread copy would hold the whole
+              // response in memory.
+              let read: Promise<string> | null = null;
+              const source = copy;
+              core.requestFinished(id, response.status, {
+                header: (name) => response.headers.get(name),
+                requestBody: init?.body,
+                graphqlReadable: source !== null,
+                ...(source
+                  ? {
+                      text: (max: number) => {
+                        read ??= readCapped(source, Math.max(max, signals.bodies ? BODY_CHARS : 0));
+                        return read.then((text) => text.slice(0, max));
+                      },
+                    }
+                  : {}),
+              });
+            });
+            return response;
+          },
+          (caught: unknown) => {
+            timed(() => {
+              if (caught instanceof DOMException && caught.name === "AbortError")
+                core.requestAborted(id);
+              else core.requestFinished(id, 0, { header: () => null, requestBody: init?.body });
+            });
+            throw caught;
+          },
+        );
+      };
+      restores.push(patch(host, "fetch", wrappedFetch as typeof fetch));
+    }
+
+    const Xhr = (win as unknown as { XMLHttpRequest?: typeof XMLHttpRequest }).XMLHttpRequest;
+    if (Xhr) {
+      const opened = new WeakMap<XMLHttpRequest, { method: string; url: string }>();
+      const proto = Xhr.prototype;
+      const originalOpen = proto.open;
+      const originalSend = proto.send;
+      const open = function (
+        this: XMLHttpRequest,
+        method: string,
+        url: string | URL,
+        ...rest: unknown[]
+      ) {
+        if (!core.stopped) timed(() => opened.set(this, { method, url: String(url) }));
+        return (originalOpen as (...args: unknown[]) => void).call(this, method, url, ...rest);
+      };
+      const send = function (
+        this: XMLHttpRequest,
+        body?: Document | XMLHttpRequestBodyInit | null,
+      ) {
+        timed(() => {
+          const info = opened.get(this);
+          if (!info || core.stopped) return;
+          const id = core.requestStarted(info.method, new URL(info.url, win.location.href).href);
+          if (id === null) return;
+          let wasAborted = false;
+          this.addEventListener("abort", () => {
+            wasAborted = true;
+          });
+          this.addEventListener("loadend", () =>
+            timed(() => {
+              if (wasAborted) {
+                core.requestAborted(id);
+                return;
+              }
+              const text = () => {
+                try {
+                  if (this.responseType === "" || this.responseType === "text")
+                    return this.responseText;
+                  if (this.responseType === "json") return JSON.stringify(this.response);
+                } catch {
+                  return null;
+                }
+                return null;
+              };
+              core.requestFinished(id, this.status, {
+                header: (name) => {
+                  try {
+                    return this.getResponseHeader(name);
+                  } catch {
+                    return null;
+                  }
+                },
+                requestBody: typeof body === "string" ? body : undefined,
+                graphqlReadable: true,
+                text: async (max) => text()?.slice(0, Math.min(max, GRAPHQL_READ_CHARS)) ?? null,
+              });
+            }),
+          );
+        });
+        return originalSend.call(this, body);
+      };
+      restores.push(patch(proto, "open", open as typeof proto.open));
+      restores.push(patch(proto, "send", send as typeof proto.send));
+    }
+  }
+
+  // ------------------------------------------------------------ performance
+  const observers: PerformanceObserver[] = [];
+  if (signals.performance && typeof PerformanceObserver === "function") {
+    const observe = (
+      type: string,
+      onEntry: (entry: PerformanceEntry) => void,
+      /** `durationThreshold` for `event` entries, which the DOM typings do not list yet. */
+      extra: { durationThreshold?: number } = {},
+    ) => {
+      try {
+        const observer = new PerformanceObserver((list) =>
+          timed(() => list.getEntries().forEach(onEntry)),
+        );
+        observer.observe({ type, buffered: true, ...extra } as PerformanceObserverInit);
+        observers.push(observer);
+      } catch {
+        // This browser does not report that entry type.
+      }
+    };
+    observe("longtask", (entry) => {
+      perf.longTasks += 1;
+      perf.longestTaskMs = Math.max(perf.longestTaskMs, entry.duration);
+    });
+    observe("largest-contentful-paint", (entry) => {
+      perf.lcpMs = entry.startTime;
+    });
+    observe("layout-shift", (entry) => {
+      const shift = entry as PerformanceEntry & { value?: number; hadRecentInput?: boolean };
+      if (!shift.hadRecentInput) perf.cls += shift.value ?? 0;
+    });
+    observe(
+      "event",
+      (entry) => {
+        const event = entry as PerformanceEntry & { interactionId?: number };
+        if (event.interactionId) perf.inpMs = Math.max(perf.inpMs, entry.duration);
+      },
+      { durationThreshold: 40 },
+    );
+  }
+
+  // ------------------------------------------------------------ the page's own sections
+  const storage = async (fileTally: RedactionTally): Promise<DebugContextFile["storage"]> => {
+    const allowed = new Set(options.storageValueKeys ?? []);
+    const read = (area: Storage | null) => {
+      if (!area) return undefined;
+      const out: { key: string; bytes: number; value?: string }[] = [];
+      try {
+        for (let index = 0; index < area.length && out.length < 100; index += 1) {
+          const key = area.key(index);
+          if (key === null) continue;
+          const value = area.getItem(key) ?? "";
+          out.push({
+            key: scrubText(key, 120, fileTally),
+            bytes: (key.length + value.length) * 2,
+            ...(allowed.has(key) ? { value: excerptOf(value, 500, fileTally) } : {}),
+          });
+        }
+      } catch {
+        return undefined;
+      }
+      return out.length ? out : undefined;
+    };
+    let local: Storage | null = null;
+    let session: Storage | null = null;
+    try {
+      local = win.localStorage;
+      session = win.sessionStorage;
+    } catch {
+      // Storage is blocked (sandboxed frame, privacy mode).
+    }
+    const cookies = win.document.cookie
+      .split(";")
+      .map((part) => part.split("=")[0]!.trim())
+      .filter(Boolean)
+      .slice(0, 50)
+      .map((name) => scrubText(name, 80, fileTally));
+    const factory = win.indexedDB as
+      | (IDBFactory & { databases?: () => Promise<Array<{ name?: string }>> })
+      | undefined;
+    const databases =
+      typeof factory?.databases === "function" ? await within(factory.databases(), 200) : undefined;
+    const indexedDb = (databases ?? [])
+      .flatMap((db) => (db.name ? [scrubText(db.name, 80, fileTally)] : []))
+      .slice(0, 30);
+    const localKeys = read(local);
+    const sessionKeys = read(session);
+    return {
+      ...(localKeys ? { local: localKeys } : {}),
+      ...(sessionKeys ? { session: sessionKeys } : {}),
+      ...(cookies.length ? { cookies } : {}),
+      ...(indexedDb.length ? { indexedDb } : {}),
+    };
+  };
+
+  const snapshot = async (input: DebugSnapshotInput = {}): Promise<DebugContextFile | null> => {
+    const reportAt = core.takeMark();
+    const fileTally = newTally();
+    const shared = await core.shared(reportAt, input.steps, fileTally, runtimeBuild);
+    const { join, routePattern, ...sections } = shared;
+    const file: DebugContextFile = { ...core.skeletonFile(reportAt, "web"), ...sections };
+    file.join = { ...file.join, ...join };
+    const nav = win.navigator;
+
+    if (signals.page) {
+      const navigations = input.steps?.filter((step) => step.type === "navigate").length ?? 0;
+      file.page = {
+        url: scrubUrl(win.location.href, 1000, undefined, fileTally),
+        route: input.anchor?.route ?? win.location.pathname,
+        ...(routePattern ? { routePattern } : {}),
+        // Titles often name a record ("Invoice for …"); a customer's report leaves them out.
+        ...(resolved.audience === "reviewer" && win.document.title
+          ? { title: scrubText(win.document.title, 160, fileTally) }
+          : {}),
+        ...(win.document.referrer
+          ? { referrer: scrubUrl(win.document.referrer, 300, undefined, fileTally) }
+          : {}),
+        loadedAgoMs: Math.max(0, Math.round(reportAt - win.performance.timeOrigin)),
+        softNavigations: Math.max(0, navigations - 1),
+        visibility: win.document.visibilityState,
+      };
+    }
+
+    if (signals.environment) {
+      const agent = nav.userAgent;
+      const media = (query: string) => {
+        try {
+          return win.matchMedia(query).matches;
+        } catch {
+          return false;
+        }
+      };
+      const connection = (nav as Navigator & { connection?: { effectiveType?: string } }).connection
+        ?.effectiveType;
+      const browser = browserName(agent);
+      const os = systemName(agent);
+      file.client = {
+        ...(browser ? { browser } : {}),
+        ...(os ? { os } : {}),
+        device: /iPad|Tablet/i.test(agent)
+          ? "tablet"
+          : /Mobi|iPhone|Android/i.test(agent)
+            ? "mobile"
+            : "desktop",
+        viewport: [win.document.documentElement.clientWidth, win.innerHeight],
+        dpr: win.devicePixelRatio || 1,
+        ...(win.visualViewport && win.visualViewport.scale !== 1
+          ? { zoom: win.visualViewport.scale }
+          : {}),
+        locale: nav.language,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        colorScheme: media("(prefers-color-scheme: dark)") ? "dark" : "light",
+        reducedMotion: media("(prefers-reduced-motion: reduce)"),
+        online: nav.onLine,
+        ...(connection ? { connection } : {}),
+        touch: (nav.maxTouchPoints ?? 0) > 0,
+      };
+    }
+
+    if (signals.target && (input.anchor || input.element)) {
+      const anchor = input.anchor;
+      file.target = {
+        ...(anchor?.component?.name ? { component: anchor.component.name } : {}),
+        ...(anchor?.component?.file ? { file: anchor.component.file } : {}),
+        ...(anchor?.stack?.length ? { stack: anchor.stack } : {}),
+        ...(anchor?.role ? { role: anchor.role } : {}),
+        ...(anchor?.accName ? { name: anchor.accName } : {}),
+        ...(anchor?.tag
+          ? { tag: anchor.tag }
+          : input.element
+            ? { tag: input.element.tagName.toLowerCase() }
+            : {}),
+      };
+      if (signals.domExcerpt && input.element?.isConnected) {
+        const element = input.element;
+        file.target.html = skeleton(element, 4096, win.location.href, fileTally);
+        const rect = element.getBoundingClientRect();
+        file.target.box = [
+          Math.round(rect.left),
+          Math.round(rect.top),
+          Math.round(rect.width),
+          Math.round(rect.height),
+        ];
+        const computed = win.getComputedStyle(element);
+        file.target.styles = Object.fromEntries(
+          STYLE_NAMES.map((name) => [name, computed.getPropertyValue(name)]),
+        );
+      }
+    }
+
+    if (signals.performance) {
+      const navigation = win.performance.getEntriesByType?.("navigation")[0] as
+        | PerformanceNavigationTiming
+        | undefined;
+      const memory = (win.performance as Performance & { memory?: { usedJSHeapSize?: number } })
+        .memory;
+      file.performance = {
+        longTasks: perf.longTasks,
+        ...(perf.longestTaskMs ? { longestTaskMs: Math.round(perf.longestTaskMs) } : {}),
+        ...(perf.inpMs ? { inpMs: Math.round(perf.inpMs) } : {}),
+        ...(perf.lcpMs ? { lcpMs: Math.round(perf.lcpMs) } : {}),
+        cls: Math.round(perf.cls * 1000) / 1000,
+        ...(navigation?.loadEventEnd ? { loadMs: Math.round(navigation.loadEventEnd) } : {}),
+        ...(memory?.usedJSHeapSize
+          ? { heapMb: Math.round(memory.usedJSHeapSize / 1_048_576) }
+          : {}),
+      };
+    }
+    if (signals.storage) file.storage = await storage(fileTally);
+    return core.finish(file, fileTally);
+  };
+
+  return {
+    mark: core.mark,
+    snapshot: async (input) => {
+      try {
+        return await snapshot(input);
+      } finally {
+        core.clearMark();
+      }
+    },
+    reportError: core.reportError,
+    stats: core.stats,
+    stop() {
+      core.stop();
+      for (const restore of restores.splice(0).reverse()) restore();
+      for (const remove of listeners.splice(0)) remove();
+      for (const observer of observers.splice(0)) observer.disconnect();
+    },
+  };
+}

package/src/runtime/details-model.ts

@@ -0,0 +1,30 @@
+/** Role and custom field values on a comment: what is turned on, and what a post sends. DOM-free. */
+import type { Details, Settings } from "./api.js";
+
+export const noDetails: Details = { role: null, fields: {} };
+
+export function detailsEnabled(settings: Settings | null) {
+  if (!settings) return false;
+  return (
+    (settings.roles.enabled && settings.roles.options.length > 0) ||
+    (settings.fields.enabled && settings.fields.items.length > 0)
+  );
+}
+
+export function hasFieldValues(details: Details) {
+  return Object.values(details.fields).some((value) => value.trim());
+}
+
+/** Only sends what is turned on, so a disabled feature never rejects a post. */
+export function detailsPayload(settings: Settings | null, details: Details): Partial<Details> {
+  if (!settings) return {};
+  const payload: Partial<Details> = {};
+  if (settings.roles.enabled && details.role) payload.role = details.role;
+  if (settings.fields.enabled) {
+    const fields = Object.fromEntries(
+      Object.entries(details.fields).filter(([, value]) => value.trim()),
+    );
+    if (Object.keys(fields).length) payload.fields = fields;
+  }
+  return payload;
+}