@lightworkai.official/debug-capture 0.6.0

package/src/capture/actionTrail.ts

@@ -0,0 +1,693 @@
+// Rolling "steps to reproduce" trail. Records recent clicks, field changes, and
+// route navigations into a bounded ring buffer. Privacy-safe: only element
+// labels and field names are kept — never typed values.
+
+import { captureOption, overlaySelectors } from '../config';
+import { redactLabel, redactUrl } from './redact';
+import type { ActionKind, ActionTrailEntry } from '../types';
+
+// Room for a merged "คลิก … → /route" row (a 40-char label + destination).
+const MAX_DETAIL_LEN = 120;
+// Per-label cap — keeps a container's text from flooding the label even when the
+// element is legitimately clickable (a card / list row).
+const LABEL_MAX = 40;
+
+const cap = (s: string, max: number): string => (s.length > max ? `${s.slice(0, max)}…` : s);
+const decodeForDisplay = (s: string): string => {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+};
+
+let buffer: ActionTrailEntry[] = [];
+let counter = 0;
+let installed = false;
+
+function push(
+  kind: ActionKind,
+  detail: string,
+  source?: string,
+  html?: string,
+): ActionTrailEntry | null {
+  const trimmed = cap(detail, MAX_DETAIL_LEN);
+  const last = buffer[buffer.length - 1];
+
+  // Collapse click → navigate: a click that immediately caused this navigation is
+  // ONE action, not two rows. Fold the real destination into the click row's
+  // visible detail and drop the redundant "ไปที่ …" row.
+  if (kind === 'navigate' && last?.kind === 'click') {
+    const navFull = trimmed.replace(/^ไปที่\s*/, '');
+    // App Router double-fires pushState+replaceState for the same url — if we've
+    // already folded this destination in, just refresh the timestamp.
+    if (last.detail.includes(`→ ${navFull}`)) {
+      last.at = new Date().toISOString();
+      return last;
+    }
+    const navPath = navFull.split(/[?#]/)[0] ?? navFull;
+    const clickDest = last.source
+      ? decodeForDisplay(last.source.replace(/^→\s*/, '')).split(/[?#]/)[0]
+      : null;
+    if (clickDest && (navPath === clickDest || navPath.startsWith(clickDest))) {
+      last.detail = cap(`${last.detail} → ${navFull}`, MAX_DETAIL_LEN);
+      last.source = undefined; // now shown inline in detail — avoid double display
+      last.at = new Date().toISOString();
+      return last;
+    }
+  }
+
+  // Collapse a consecutive duplicate instead of adding a new row. Navigations
+  // routinely double-fire, so those just refresh the timestamp; repeated
+  // clicks/edits keep a ×count — a genuine signal (e.g. a user clicked a dead
+  // button several times).
+  if (last && last.kind === kind && last.detail === trimmed) {
+    last.at = new Date().toISOString();
+    if (kind !== 'navigate') last.count = (last.count ?? 1) + 1;
+    return last;
+  }
+  counter += 1;
+  const entry: ActionTrailEntry = {
+    id: `act_${counter}`,
+    at: new Date().toISOString(),
+    kind,
+    detail: trimmed,
+    count: 1,
+    source,
+    html: claimBudget(html),
+  };
+  buffer.push(entry);
+  while (buffer.length > captureOption('maxActions')) releaseBudget(buffer.shift());
+  return entry;
+}
+
+// ── Snapshot size budget ─────────────────────────────────────────────────────
+// Every snapshot ships inside the ticket payload, and this file now captures up
+// to three per action (control, its after-state, any overlay it opened). Without
+// a ceiling a long session on a dialog-heavy page could push a multi-megabyte
+// report through the ticket API. Oldest-out: evicting a trail row returns its
+// bytes, so a long session keeps capturing rather than going text-only forever
+// after one big dialog.
+const HTML_BUDGET = 200_000;
+let htmlBytes = 0;
+
+function claimBudget(html: string | undefined): string | undefined {
+  if (!html) return undefined;
+  if (htmlBytes + html.length > HTML_BUDGET) return undefined;
+  htmlBytes += html.length;
+  return html;
+}
+
+function releaseBudget(entry: ActionTrailEntry | undefined): void {
+  if (!entry) return;
+  htmlBytes -= (entry.html?.length ?? 0) + (entry.afterHtml?.length ?? 0);
+  if (htmlBytes < 0) htmlBytes = 0;
+}
+
+/** Display suffix for a collapsed repeated action, e.g. " (×4)". Empty for a
+ *  single occurrence — shared by the report text + the in-dialog preview. */
+export function actionCountSuffix(count?: number): string {
+  return count && count > 1 ? ` (×${count})` : '';
+}
+
+// Skip the reporter's own UI (button, modal, annotator canvas) — interacting
+// with the report tool isn't part of reproducing the user's issue.
+function isReporterUi(target: EventTarget | null): boolean {
+  return target instanceof Element && Boolean(target.closest('[data-debug-reporter]'));
+}
+
+// Which elements count as a "click target": a native/ARIA control, or a custom
+// clickable element (a React onClick within a few hops). A plain layout container
+// with neither is an accidental / background click and is skipped.
+const INTERACTIVE_SELECTOR =
+  'button, a[href], [role="button"], [role="tab"], [role="menuitem"], [role="option"], [role="switch"], [role="checkbox"], [role="radio"], [role="link"], summary, input, select, textarea';
+
+// Friendly Thai nouns so a step reads "คลิก ปุ่ม …" / "คลิก ลิงก์ …" instead of a
+// raw DOM tag. Role wins over tag (a <div role="button"> is a ปุ่ม).
+const NOUN_BY_TAG: Record<string, string> = {
+  button: 'ปุ่ม',
+  a: 'ลิงก์',
+  input: 'ช่อง',
+  textarea: 'ช่อง',
+  select: 'ตัวเลือก',
+  summary: 'ส่วนขยาย',
+};
+const NOUN_BY_ROLE: Record<string, string> = {
+  button: 'ปุ่ม',
+  tab: 'แท็บ',
+  menuitem: 'เมนู',
+  option: 'ตัวเลือก',
+  switch: 'สวิตช์',
+  checkbox: 'ช่องเลือก',
+  radio: 'ตัวเลือก',
+  link: 'ลิงก์',
+};
+
+function nounOf(el: Element): string {
+  const role = el.getAttribute('role');
+  if (role && NOUN_BY_ROLE[role]) return NOUN_BY_ROLE[role];
+  // Custom clickable div/span (React onClick) has no mapping → read as "ปุ่ม".
+  return NOUN_BY_TAG[el.tagName.toLowerCase()] ?? 'ปุ่ม';
+}
+
+// Nearest element (self + a few DOM ancestors) carrying a React onClick — catches
+// custom clickable div/span (nav cards, list rows) while ignoring layout-only
+// containers. Bounded hops so a far page-level handler doesn't falsely qualify.
+function nearestReactClickable(el: Element, maxHops: number): Element | null {
+  try {
+    let node: Element | null = el;
+    let hops = 0;
+    while (node && hops <= maxHops) {
+      const fiber = fiberOf(node);
+      if (fiber && typeof fiber.memoizedProps?.onClick === 'function') return node;
+      node = node.parentElement;
+      hops += 1;
+    }
+  } catch {
+    // Fiber internals absent/changed — treat as not clickable.
+  }
+  return null;
+}
+
+// Accessible name, preferring explicit labels over the (potentially huge)
+// descendant text. Only falls back to `textContent` for leaf-ish controls; a link
+// with no text uses its (decoded) destination path.
+function accessibleName(el: Element): string {
+  const aria = el.getAttribute('aria-label')?.trim();
+  if (aria) return aria;
+  const title = el.getAttribute('title')?.trim();
+  if (title) return title;
+  if (
+    el instanceof HTMLInputElement ||
+    el instanceof HTMLTextAreaElement ||
+    el instanceof HTMLSelectElement
+  ) {
+    return (el.getAttribute('placeholder') || el.getAttribute('name') || '').trim();
+  }
+  if (el instanceof HTMLImageElement) return (el.getAttribute('alt') || '').trim();
+  const text = (el.textContent ?? '').replace(/\s+/g, ' ').trim();
+  if (text) return text;
+  if (el instanceof HTMLAnchorElement) {
+    const href = el.getAttribute('href');
+    if (href?.startsWith('/')) return decodeForDisplay(href);
+  }
+  return '';
+}
+
+// The element a click should be attributed to: a real control, or a custom
+// clickable element — else null (a click on a layout container / empty page area
+// is not a reproduction step).
+function resolveClickTarget(target: EventTarget | null): Element | null {
+  if (!(target instanceof Element)) return null;
+  const el = target.closest(INTERACTIVE_SELECTOR) ?? nearestReactClickable(target, 4);
+  if (!el) return null;
+  const tag = el.tagName.toLowerCase();
+  if (tag === 'html' || tag === 'body') return null;
+  return el;
+}
+
+function describeLabel(el: Element): string | null {
+  const name = redactLabel(accessibleName(el));
+  if (!name) return null; // icon-only with no aria/title/href → nothing to say → skip
+  return `${nounOf(el)} “${cap(name, LABEL_MAX)}”`;
+}
+
+// ── Element HTML snapshot ─────────────────────────────────────────────────────
+// A small, sanitized + redacted outerHTML of the clicked control so the admin
+// trail can render the ACTUAL element (styled by the app's own Tailwind, since
+// it's viewed in-app). Bounded — a giant card falls back to a text-only row.
+const MAX_RAW_HTML = 6000; // skip capture when the element's raw HTML exceeds this
+const MAX_HTML = 4000; // drop the snapshot if still big after cleaning
+
+// Classes that would let a captured element escape its preview box (positioning /
+// full-viewport size). Stripped so a snapshot can never cover the admin page.
+const ESCAPE_CLASS_RE =
+  /(?:^|\s)!?(?:fixed|absolute|sticky|inset-\S+|z-\S+|top-\S+|bottom-\S+|left-\S+|right-\S+|w-screen|h-screen|min-h-screen|max-h-screen|translate-\S+|scale-\S+)(?=\s|$)/g;
+
+function sanitizeCaptureHtml(root: Element): void {
+  // Drop elements that can't / shouldn't render in a static preview.
+  root
+    .querySelectorAll('script, style, link, iframe, object, embed, noscript, canvas, video, audio')
+    .forEach((n) => n.remove());
+  const nodes: Element[] = [root, ...Array.from(root.querySelectorAll('*'))];
+  for (const node of nodes) {
+    for (const attr of Array.from(node.attributes)) {
+      const name = attr.name.toLowerCase();
+      // Strip handlers, input values, and data-* (may carry PII); keep class/style.
+      if (
+        name.startsWith('on') ||
+        name === 'srcdoc' ||
+        name === 'value' ||
+        name.startsWith('data-')
+      ) {
+        node.removeAttribute(attr.name);
+      }
+    }
+    if (node instanceof HTMLAnchorElement) node.setAttribute('href', '#');
+    if (node instanceof HTMLImageElement) node.removeAttribute('src'); // avoid broken/auth-gated loads
+    const cls = node.getAttribute('class');
+    if (cls) {
+      const cleaned = cls.replace(ESCAPE_CLASS_RE, ' ').replace(/\s+/g, ' ').trim();
+      if (cleaned) node.setAttribute('class', cleaned);
+      else node.removeAttribute('class');
+    }
+  }
+  // Redact visible text (a name / number a container might carry).
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let text = walker.nextNode();
+  while (text) {
+    if (text.nodeValue) text.nodeValue = redactLabel(text.nodeValue);
+    text = walker.nextNode();
+  }
+}
+
+function captureElementHtml(el: Element, maxRaw: number, maxOut: number): string | undefined {
+  try {
+    const raw = el.outerHTML;
+    if (!raw || raw.length > maxRaw) return undefined; // too big → text-only
+    const clone = el.cloneNode(true) as Element;
+    sanitizeCaptureHtml(clone);
+    const html = clone.outerHTML;
+    return html && html.length <= maxOut ? html : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const captureClickHtml = (el: Element): string | undefined =>
+  captureElementHtml(el, MAX_RAW_HTML, MAX_HTML);
+
+// A dialog is the whole point of the click that opened it, so it gets a bigger
+// allowance than a button — but still bounded, and still subject to the shared
+// budget above.
+const MAX_RAW_OVERLAY_HTML = 150_000;
+const MAX_OVERLAY_HTML = 40_000;
+
+const captureOverlayHtml = (el: Element): string | undefined =>
+  captureElementHtml(el, MAX_RAW_OVERLAY_HTML, MAX_OVERLAY_HTML);
+
+function describeField(target: EventTarget | null): string | null {
+  if (
+    !(target instanceof HTMLInputElement) &&
+    !(target instanceof HTMLTextAreaElement) &&
+    !(target instanceof HTMLSelectElement)
+  ) {
+    return null;
+  }
+  const name =
+    target.name ||
+    target.id ||
+    target.getAttribute('aria-label') ||
+    target.getAttribute('placeholder') ||
+    target.tagName.toLowerCase();
+  // Value is never recorded — only that the field changed (name is redacted too).
+  return `ช่อง “${redactLabel(name)}”`;
+}
+
+// ── Nav-target attribution (best-effort, read-only, fully guarded) ───────────
+// Enriches a click with WHERE it leads — resolved the SAME way in dev / uat /
+// prod:
+//   • a link's DOM `href` (cleanest), else
+//   • the target parsed from the nearest `onClick` handler — the string literal
+//     survives minification, so `router.push('/x')` still resolves in prod.
+// Deliberately NO dev-only React debug info: `_debugOwner` (component name) and
+// `_debugSource` (file:line) are stripped from production builds and names are
+// minified, so they'd behave differently per environment — which we don't want.
+// A source file:line that works in prod would require a build-time JSX
+// annotation (à la Sentry) — a separate build-infra change.
+const MAX_SOURCE_LEN = 80;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Fiber = any;
+
+function fiberOf(node: Element): Fiber | null {
+  const key = Object.keys(node).find(
+    (k) => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$'),
+  );
+  return key ? (node as unknown as Record<string, Fiber>)[key] : null;
+}
+
+function navTargetOf(onClick: unknown): string | null {
+  if (typeof onClick !== 'function') return null;
+  try {
+    const src = Function.prototype.toString.call(onClick);
+    // router.push('/x') / .replace('/x') / redirect('/x') — the string literal
+    // survives minification even when the router identifier is mangled.
+    const match =
+      src.match(/\.(?:push|replace)\(\s*['"`]([^'"`]+)['"`]/) ??
+      src.match(/redirect\(\s*['"`]([^'"`]+)['"`]/);
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function navLabel(target: string | null): string | undefined {
+  if (!target) return undefined;
+  const trimmed = target.length > MAX_SOURCE_LEN ? `${target.slice(0, MAX_SOURCE_LEN)}…` : target;
+  return `→ ${trimmed}`;
+}
+
+function describeClickSource(el: Element): string | undefined {
+  try {
+    // Prefer the link's DOM href — cleanest, and identical across environments.
+    const anchorHref = el.closest('a[href]')?.getAttribute('href');
+    if (anchorHref && anchorHref.startsWith('/')) return navLabel(anchorHref);
+
+    // Otherwise, the nearest onClick's target (e.g. a `div` that router.push-es).
+    let fiber = fiberOf(el);
+    let hops = 0;
+    while (fiber && hops < 30) {
+      if (typeof fiber.memoizedProps?.onClick === 'function') {
+        return navLabel(navTargetOf(fiber.memoizedProps.onClick));
+      }
+      fiber = fiber.return;
+      hops += 1;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Consequence capture ──────────────────────────────────────────────────────
+// A click's resting snapshot says what was PRESSED; it says nothing about what
+// pressing it did. Reports kept arriving as "คลิก ตราประทับ" with no sign of the
+// dialog that opened, the button going into its loading state, or the error
+// toast that followed — all of which the user saw and none of which was in the
+// log. These two observers record that half.
+
+/** Things that APPEAR over the page and are the visible result of an action.
+ *  Radix (dialog / sheet / dropdown / popover) lands on the ARIA roles; sonner
+ *  toasts carry their own attribute and matter most of all — an error toast is
+ *  usually the report's whole subject. */
+const OVERLAY_SELECTOR_FALLBACK =
+  '[role="dialog"], [role="alertdialog"], [role="menu"], [role="listbox"], [role="status"], [role="alert"]';
+
+/** ARIA roles cover most component libraries; a host can name its own. */
+function overlaySelector(): string {
+  const custom = overlaySelectors();
+  return custom.length ? custom.join(', ') : OVERLAY_SELECTOR_FALLBACK;
+}
+
+function overlayNoun(el: Element): string {
+  const role = el.getAttribute('role');
+  if (role === 'status' || role === 'alert') return 'ข้อความแจ้งเตือน';
+  if (role === 'menu') return 'เมนู';
+  if (role === 'listbox') return 'รายการตัวเลือก';
+  if (role === 'alertdialog') return 'กล่องยืนยัน';
+  return 'กล่องโต้ตอบ';
+}
+
+/** Accessible title of an overlay, preferring the labelled title over its full
+ *  body text (a dialog's textContent is the entire form). */
+function overlayTitle(el: Element): string {
+  const aria = el.getAttribute('aria-label')?.trim();
+  if (aria) return aria;
+  const labelledBy = el.getAttribute('aria-labelledby');
+  if (labelledBy) {
+    const label = labelledBy
+      .split(/\s+/)
+      .map((id) => document.getElementById(id)?.textContent?.trim() ?? '')
+      .filter(Boolean)
+      .join(' ');
+    if (label) return label;
+  }
+  const heading = el.querySelector('[data-slot="dialog-title"], h1, h2, h3, [role="heading"]');
+  const headingText = heading?.textContent?.replace(/\s+/g, ' ').trim();
+  if (headingText) return headingText;
+  // Toasts have no heading — their body IS the message.
+  return (el.textContent ?? '').replace(/\s+/g, ' ').trim();
+}
+
+function overlayDetail(el: Element): string {
+  const title = redactLabel(overlayTitle(el));
+  const noun = overlayNoun(el);
+  return title ? `เปิด ${noun} “${cap(title, LABEL_MAX)}”` : `เปิด ${noun}`;
+}
+
+// An overlay is mounted EMPTY and fills in from an API call, so snapshotting it
+// the instant it appears captures a skeleton and the title "กำลังโหลด…" — the
+// one state nobody needs.
+//
+// "Stopped changing" is NOT the signal. While a request is in flight the DOM is
+// perfectly still — that stillness IS the loading state, so a quiet-period
+// detector fires at exactly the wrong moment. The overlay has to be quiet AND
+// not be showing anything that says it is still working.
+
+/** Marks a subtree as still working. Covers the two ways this app shows it —
+ *  ARIA state and skeleton classes — plus the literal text, since a plain
+ *  "กำลังโหลด…" div carries no attribute at all. */
+const LOADING_SELECTOR =
+  '[aria-busy="true"], [role="progressbar"], [data-loading="true"], .animate-pulse, .animate-spin';
+const LOADING_TEXT_RE = /กำลังโหลด|กำลังค้นหา|กำลังดำเนินการ|\bloading\b/i;
+
+function looksLoading(el: Element): boolean {
+  if (el.querySelector(LOADING_SELECTOR)) return true;
+  return LOADING_TEXT_RE.test(el.textContent ?? '');
+}
+
+/** Quiet period required before a snapshot — spans the gap between a response
+ *  landing and the list painting. */
+const OVERLAY_SETTLE_MS = 400;
+/** How often to re-check. A fetch finishing produces mutations, but the LAST
+ *  meaningful moment (the spinner being removed) can be several frames earlier
+ *  than the quiet window closes, so this is polled rather than event-driven. */
+const OVERLAY_POLL_MS = 250;
+/** Hard stop. Generous, because a slow dialog is exactly the one worth seeing;
+ *  at the deadline we capture whatever is on screen, loading or not — a
+ *  mid-flight snapshot beats none. */
+const OVERLAY_MAX_WAIT_MS = 8000;
+
+/** Snapshot `el` once it has both settled and stopped claiming to load,
+ *  amending the row already pushed so the trail keeps its true ordering. */
+function captureOverlayWhenSettled(el: Element, entry: ActionTrailEntry): void {
+  if (typeof MutationObserver === 'undefined') {
+    entry.html = claimBudget(captureOverlayHtml(el));
+    return;
+  }
+  let lastChangeAt = Date.now();
+  let done = false;
+
+  const stop = () => {
+    done = true;
+    observer.disconnect();
+    window.clearInterval(poll);
+    window.clearTimeout(deadline);
+  };
+
+  const finish = () => {
+    if (done) return;
+    stop();
+    // Dismissed before it ever settled — nothing left to photograph, and the
+    // row still records that it opened.
+    if (!el.isConnected) return;
+    // Re-read the title too: it was "กำลังโหลด…" when the row was pushed.
+    entry.detail = cap(overlayDetail(el), MAX_DETAIL_LEN);
+    entry.html = claimBudget(captureOverlayHtml(el));
+  };
+
+  const observer = new MutationObserver(() => {
+    lastChangeAt = Date.now();
+  });
+  observer.observe(el, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    characterData: true,
+  });
+
+  const poll = window.setInterval(() => {
+    if (done) return;
+    if (!el.isConnected) {
+      stop();
+      return;
+    }
+    const quiet = Date.now() - lastChangeAt >= OVERLAY_SETTLE_MS;
+    if (quiet && !looksLoading(el)) finish();
+  }, OVERLAY_POLL_MS);
+
+  const deadline = window.setTimeout(finish, OVERLAY_MAX_WAIT_MS);
+}
+
+function recordOverlay(el: Element): void {
+  if (isReporterUi(el)) return;
+  // Pushed NOW so the row sits in the right place in the sequence; the snapshot
+  // and final title arrive a moment later, once the content has loaded.
+  const entry = push('ui', overlayDetail(el));
+  if (entry) captureOverlayWhenSettled(el, entry);
+}
+
+function installOverlayWatcher(): void {
+  if (typeof MutationObserver === 'undefined') return;
+  const seen = new WeakSet<Element>();
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of Array.from(mutation.addedNodes)) {
+        if (!(node instanceof Element)) continue;
+        // A portal mounts the whole overlay as ONE added node, so check the node
+        // itself before searching inside it.
+        const selector = overlaySelector();
+        const roots = node.matches(selector) ? [node] : Array.from(node.querySelectorAll(selector));
+        for (const root of roots) {
+          // Radix mounts a dialog hidden then reveals it, so the same element can
+          // surface twice; WeakSet keeps one row per element without leaking.
+          if (seen.has(root)) continue;
+          seen.add(root);
+          recordOverlay(root);
+        }
+      }
+    }
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+}
+
+// ── Post-click state of the clicked control ──────────────────────────────────
+
+/** How long to wait for a click to visibly change its control. Long enough for
+ *  a request to put a button into its loading state, short enough that an
+ *  unrelated later re-render is not misattributed to this click. */
+const AFTER_WATCH_MS = 1600;
+/** The after-state is a second copy of the same control, so it is capped
+ *  tighter than the original — it exists to show a state flip, not detail. */
+const MAX_AFTER_HTML = 2500;
+
+interface ControlState {
+  disabled: boolean;
+  busy: boolean;
+  text: string;
+}
+
+function readControlState(el: Element): ControlState {
+  return {
+    disabled:
+      el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true',
+    busy: el.getAttribute('aria-busy') === 'true',
+    text: cap((el.textContent ?? '').replace(/\s+/g, ' ').trim(), LABEL_MAX),
+  };
+}
+
+/** Thai description of the flip, or null when nothing meaningful changed.
+ *  Ordered by how much each fact explains: gone > disabled > busy > relabelled. */
+function describeStateChange(before: ControlState, after: ControlState): string | null {
+  if (!before.disabled && after.disabled) return 'ปุ่มถูกปิดใช้งานหลังคลิก';
+  if (!before.busy && after.busy) return 'ปุ่มเข้าสู่สถานะกำลังโหลด';
+  if (before.text !== after.text && after.text) {
+    return `ข้อความเปลี่ยนเป็น “${after.text}”`;
+  }
+  return null;
+}
+
+/** Watch the clicked control briefly and record the first meaningful change. */
+function watchAfterState(el: Element, entry: ActionTrailEntry): void {
+  if (typeof MutationObserver === 'undefined') return;
+  const before = readControlState(el);
+  let settled = false;
+
+  const finish = (note: string, capture: boolean) => {
+    if (settled) return;
+    settled = true;
+    observer.disconnect();
+    window.clearTimeout(timer);
+    entry.afterNote = note;
+    if (capture) {
+      entry.afterHtml = claimBudget(captureElementHtml(el, MAX_RAW_HTML, MAX_AFTER_HTML));
+    }
+  };
+
+  const observer = new MutationObserver(() => {
+    // Removed from the page — a dialog closed over it, or the view swapped.
+    // Nothing left to snapshot, but the fact itself is worth recording.
+    if (!el.isConnected) {
+      finish('องค์ประกอบหายไปจากหน้าจอ', false);
+      return;
+    }
+    const note = describeStateChange(before, readControlState(el));
+    if (note) finish(note, true);
+  });
+  observer.observe(el, {
+    attributes: true,
+    attributeFilter: ['disabled', 'aria-disabled', 'aria-busy', 'class'],
+    childList: true,
+    subtree: true,
+    characterData: true,
+  });
+  // Detaching a subtree does not notify an observer bound to it, so the removal
+  // case needs its own check at the deadline.
+  const timer = window.setTimeout(() => {
+    if (!settled && !el.isConnected) {
+      finish('องค์ประกอบหายไปจากหน้าจอ', false);
+      return;
+    }
+    settled = true;
+    observer.disconnect();
+  }, AFTER_WATCH_MS);
+}
+
+export function installActionTrail(): void {
+  if (installed || typeof window === 'undefined') return;
+  installed = true;
+
+  document.addEventListener(
+    'click',
+    (event) => {
+      if (isReporterUi(event.target)) return;
+      const el = resolveClickTarget(event.target);
+      if (!el) return;
+      const label = describeLabel(el);
+      if (!label) return;
+      const entry = push('click', `คลิก ${label}`, describeClickSource(el), captureClickHtml(el));
+      // Record what the click DID to the control (loading / disabled / gone).
+      if (entry) watchAfterState(el, entry);
+    },
+    { capture: true, passive: true },
+  );
+
+  document.addEventListener(
+    'change',
+    (event) => {
+      if (isReporterUi(event.target)) return;
+      const detail = describeField(event.target);
+      if (detail) push('input', `แก้ไข ${detail}`);
+    },
+    { capture: true, passive: true },
+  );
+
+  document.addEventListener(
+    'submit',
+    (event) => {
+      if (isReporterUi(event.target)) return;
+      push('submit', 'ส่งฟอร์ม');
+    },
+    { capture: true, passive: true },
+  );
+
+  // Route changes — App Router navigates via history.pushState/replaceState.
+  // Decode for display so Thai query params read as text, not `%E0%B8…`.
+  const record = () =>
+    push('navigate', `ไปที่ ${decodeForDisplay(redactUrl(location.pathname + location.search))}`);
+  const originalPush = history.pushState.bind(history);
+  const originalReplace = history.replaceState.bind(history);
+  history.pushState = ((...args: Parameters<History['pushState']>) => {
+    const result = originalPush(...args);
+    record();
+    return result;
+  }) as History['pushState'];
+  history.replaceState = ((...args: Parameters<History['replaceState']>) => {
+    const result = originalReplace(...args);
+    record();
+    return result;
+  }) as History['replaceState'];
+  window.addEventListener('popstate', record);
+
+  installOverlayWatcher();
+}
+
+export function getActionTrail(): ActionTrailEntry[] {
+  return buffer.map((entry) => ({ ...entry }));
+}
+
+export function clearActionTrail(): void {
+  buffer = [];
+  htmlBytes = 0;
+}