@lightworkai.official/debug-capture 0.6.0

package/src/mytickets/strings.ts

@@ -0,0 +1,217 @@
+/**
+ * The tickets panel's own words, kept apart from the reporter dialog's so
+ * neither grows the other's vocabulary. Thai wording is the original's, verbatim
+ * where the original had one.
+ */
+export interface TicketStrings {
+  title: string;
+  intro: string;
+  searchPlaceholder: string;
+  searchLabel: string;
+  allStatuses: string;
+  count: (n: number) => string;
+  colNumber: string;
+  colTitle: string;
+  colModule: string;
+  colStatus: string;
+  colResponse: string;
+  colCreated: string;
+  colUpdated: string;
+  awaitingReply: string;
+  hasSolution: string;
+  hasReply: string;
+  noReply: string;
+  empty: string;
+  emptyFiltered: string;
+  loading: string;
+  listFailed: string;
+  detailFailed: string;
+  signedOut: string;
+  back: string;
+  reportedBy: string;
+  conversation: string;
+  resolution: string;
+  noMessages: string;
+  you: string;
+  team: string;
+  /** The role chip beside a reporter's name, as the original prints it. */
+  reporterRole: string;
+  edited: string;
+  edit: string;
+  saveEdit: string;
+  cancel: string;
+  replyPlaceholder: string;
+  bold: string;
+  italic: string;
+  underline: string;
+  strike: string;
+  code: string;
+  blockquote: string;
+  bulletList: string;
+  orderedList: string;
+  link: string;
+  linkPrompt: string;
+  linkNeedsSelection: string;
+  linkInvalid: string;
+  attachImage: string;
+  uploading: string;
+  send: string;
+  sending: string;
+  sent: string;
+  sendFailed: string;
+  reopen: string;
+  reopenHint: string;
+  reopening: string;
+  reopened: string;
+  reopenFailed: string;
+  close: string;
+  retry: string;
+  page: string;
+  of: (page: number, pages: number) => string;
+  prev: string;
+  next: string;
+}
+
+const th: TicketStrings = {
+  title: "ปัญหาที่แจ้ง",
+  // The original names the toolbar button and points at it ("จากปุ่ม 🐞 รายงานปัญหา
+  // ที่แถบด้านบนขวา"). A package cannot: the host decides whether that button
+  // exists and where it sits, and a sentence describing a button that is not
+  // there is worse than no sentence.
+  intro: "ปัญหาที่คุณแจ้งไว้ พร้อมสถานะล่าสุด",
+  searchPlaceholder: "ค้นหาเลขที่/หัวข้อ/โมดูล",
+  searchLabel: "ค้นหาปัญหาที่แจ้ง",
+  allStatuses: "ทุกสถานะ",
+  count: (n) => `${n} รายการ`,
+  colNumber: "เลขที่",
+  colTitle: "หัวข้อ",
+  colModule: "โมดูล",
+  colStatus: "สถานะ",
+  colResponse: "คำตอบจากทีม",
+  colCreated: "แจ้งเมื่อ",
+  colUpdated: "อัปเดตล่าสุด",
+  awaitingReply: "รอคุณตอบกลับ",
+  hasSolution: "มีวิธีแก้ไข",
+  hasReply: "ตอบกลับแล้ว",
+  noReply: "ยังไม่มีการตอบกลับ",
+  empty: "คุณยังไม่ได้แจ้งปัญหา",
+  emptyFiltered: "ไม่พบรายการที่ตรงกับการค้นหา",
+  loading: "กำลังโหลด…",
+  listFailed: "โหลดรายการไม่สำเร็จ",
+  detailFailed: "โหลดรายงานไม่สำเร็จ",
+  signedOut: "กรุณาเข้าสู่ระบบเพื่อดูปัญหาที่แจ้งไว้",
+  back: "กลับไปรายการ",
+  reportedBy: "แจ้งเมื่อ",
+  conversation: "การสนทนา",
+  resolution: "วิธีแก้ไข",
+  noMessages: "ยังไม่มีข้อความ",
+  you: "คุณ",
+  team: "ทีมงาน",
+  reporterRole: "ผู้แจ้ง",
+  edited: "แก้ไขแล้ว",
+  edit: "แก้ไข",
+  saveEdit: "บันทึกการแก้ไข",
+  cancel: "ยกเลิก",
+  replyPlaceholder: "พิมพ์ข้อความถึงทีมงาน",
+  bold: "ตัวหนา",
+  italic: "ตัวเอียง",
+  underline: "ขีดเส้นใต้",
+  strike: "ขีดฆ่า",
+  code: "โค้ด",
+  blockquote: "ยกคำพูด",
+  bulletList: "รายการหัวข้อ",
+  orderedList: "รายการตัวเลข",
+  link: "ลิงก์",
+  linkPrompt: "ใส่ลิงก์",
+  linkNeedsSelection: "เลือกข้อความที่ต้องการทำลิงก์ก่อน",
+  linkInvalid: "ลิงก์ต้องขึ้นต้นด้วย http:// หรือ https://",
+  attachImage: "แนบรูป",
+  uploading: "กำลังอัปโหลดรูป…",
+  send: "ส่งข้อความ",
+  sending: "กำลังส่ง…",
+  sent: "ส่งข้อความแล้ว",
+  sendFailed: "ส่งไม่สำเร็จ ลองใหม่อีกครั้ง",
+  reopen: "ยังมีปัญหา",
+  reopenHint: "ถ้าปัญหายังไม่หาย แจ้งทีมงานอีกครั้งได้",
+  reopening: "กำลังแจ้ง…",
+  reopened: "แจ้งทีมงานอีกครั้งแล้ว — เรากำลังดูให้ครับ",
+  reopenFailed: "เปิดเรื่องไม่สำเร็จ ลองใหม่อีกครั้ง",
+  close: "ปิด",
+  retry: "ลองใหม่",
+  page: "หน้า",
+  of: (page, pages) => `หน้า ${page} จาก ${pages}`,
+  prev: "ก่อนหน้า",
+  next: "ถัดไป",
+};
+
+const en: TicketStrings = {
+  title: "My reports",
+  intro: "The problems you have reported, with their latest status",
+  searchPlaceholder: "Search number / title / module",
+  searchLabel: "Search my reports",
+  allStatuses: "All statuses",
+  count: (n) => `${n} item${n === 1 ? "" : "s"}`,
+  colNumber: "No.",
+  colTitle: "Title",
+  colModule: "Module",
+  colStatus: "Status",
+  colResponse: "Team response",
+  colCreated: "Reported",
+  colUpdated: "Last update",
+  awaitingReply: "Awaiting your reply",
+  hasSolution: "Solution provided",
+  hasReply: "Replied",
+  noReply: "No reply yet",
+  empty: "You have not reported anything yet",
+  emptyFiltered: "Nothing matches that search",
+  loading: "Loading…",
+  listFailed: "Could not load your reports",
+  detailFailed: "Could not load this report",
+  signedOut: "Sign in to see the problems you have reported",
+  back: "Back to the list",
+  reportedBy: "Reported",
+  conversation: "Conversation",
+  resolution: "Solution",
+  noMessages: "No messages yet",
+  you: "You",
+  team: "Support",
+  reporterRole: "Reporter",
+  edited: "edited",
+  edit: "Edit",
+  saveEdit: "Save changes",
+  cancel: "Cancel",
+  replyPlaceholder: "Write a message to the team",
+  bold: "Bold",
+  italic: "Italic",
+  underline: "Underline",
+  strike: "Strikethrough",
+  code: "Code",
+  blockquote: "Quote",
+  bulletList: "Bulleted list",
+  orderedList: "Numbered list",
+  link: "Link",
+  linkPrompt: "Enter a link",
+  linkNeedsSelection: "Select the text you want to link first",
+  linkInvalid: "A link must start with http:// or https://",
+  attachImage: "Add an image",
+  uploading: "Uploading the image…",
+  send: "Send",
+  sending: "Sending…",
+  sent: "Message sent",
+  sendFailed: "Could not send — try again",
+  reopen: "Still a problem",
+  reopenHint: "If the problem is not fixed, tell the team again",
+  reopening: "Sending…",
+  reopened: "The team has been notified — we are looking at it",
+  reopenFailed: "Could not reopen — try again",
+  close: "Close",
+  retry: "Try again",
+  page: "Page",
+  of: (page, pages) => `Page ${page} of ${pages}`,
+  prev: "Previous",
+  next: "Next",
+};
+
+export function ticketStrings(locale: "th" | "en" | undefined): TicketStrings {
+  return locale === "en" ? en : th;
+}

package/src/mytickets/toolbar.ts

@@ -0,0 +1,48 @@
+/**
+ * Which controls a rich composer offers.
+ *
+ * A list rather than a fixed set, because the original itself has two —
+ * `NOTE_TOOLBAR` for replies and a longer one for articles — and the support app's
+ * admin composer wants a few more than a reporter's does. The alternative was a
+ * second editor component, which is the thing this package exists to stop.
+ */
+export type EditorTool =
+  | "bold"
+  | "italic"
+  | "underline"
+  | "strike"
+  | "code"
+  | "bulletList"
+  | "orderedList"
+  | "blockquote"
+  | "link"
+  | "image";
+
+/** The original's own NOTE_TOOLBAR — what a reporter replying to a ticket gets. */
+export const NOTE_TOOLBAR: EditorTool[] = [
+  "bold",
+  "italic",
+  "underline",
+  "bulletList",
+  "orderedList",
+  "link",
+  "image",
+];
+
+/**
+ * Everything, for a staff composer. Adds the three the admin side had grown on
+ * its own — strike, code and blockquote — so adopting this component costs the
+ * app nothing it already had.
+ */
+export const FULL_TOOLBAR: EditorTool[] = [
+  "bold",
+  "italic",
+  "underline",
+  "strike",
+  "code",
+  "bulletList",
+  "orderedList",
+  "blockquote",
+  "link",
+  "image",
+];

package/src/reporter.ts

@@ -0,0 +1,53 @@
+/**
+ * The bus between "something happened" and "the reporter opens".
+ *
+ * Replaces the original's zustand store. Not because zustand is bad, but
+ * because it is React's: this package is consumed by Vue and Angular apps too,
+ * and a state library in the core would be a framework choice imposed on all of
+ * them for the sake of two callbacks and a Set.
+ *
+ * `launch` must be called INSIDE the user's gesture. Screen capture asks the
+ * browser for permission, and a browser only grants that to a real click — an
+ * await before it and the request is refused with no useful error.
+ */
+import type { DebugReason } from "./types";
+
+type Listener = (reason: DebugReason) => void;
+
+const launchListeners = new Set<Listener>();
+const crashListeners = new Set<Listener>();
+
+function subscribe(set: Set<Listener>, fn: Listener): () => void {
+  set.add(fn);
+  return () => set.delete(fn);
+}
+
+function emit(set: Set<Listener>, reason: DebugReason): void {
+  // Copied first: a listener that unsubscribes itself while we iterate would
+  // otherwise skip the next one.
+  for (const fn of [...set]) fn(reason);
+}
+
+/** The reporter UI subscribes here. */
+export function onLaunch(fn: Listener): () => void {
+  return subscribe(launchListeners, fn);
+}
+
+/** Open the reporter. Call from inside a click handler — see the note above. */
+export function launch(reason: DebugReason = { type: "manual" }): void {
+  emit(launchListeners, reason);
+}
+
+/**
+ * A crash was caught. Deliberately NOT the same channel as `launch`: opening a
+ * screen-capture prompt on its own, with no gesture behind it, is both refused
+ * by the browser and rude. A listener turns this into an invitation — a toast
+ * with a button — and that button calls `launch`.
+ */
+export function onCrash(fn: Listener): () => void {
+  return subscribe(crashListeners, fn);
+}
+
+export function emitCrash(reason: DebugReason): void {
+  emit(crashListeners, reason);
+}

package/src/screenshot.ts

@@ -0,0 +1,238 @@
+// Screenshot capture via the native Screen Capture API (getDisplayMedia). With
+// `preferCurrentTab` this captures the whole current tab — INCLUDING the
+// cross-origin OnlyOffice document iframe, which DOM-rendering libraries cannot
+// reach. Falls back to html-to-image only if the user denies the permission or
+// the browser lacks support.
+
+import { getConfig } from './config';
+import type { ScreenshotMethod } from './types';
+
+export interface ScreenshotResult {
+  dataUrl: string | null;
+  method: ScreenshotMethod;
+}
+
+// Chromium-only options not yet in the standard lib.dom typings.
+type ExtendedDisplayMediaOptions = DisplayMediaStreamOptions & {
+  preferCurrentTab?: boolean;
+  selfBrowserSurface?: 'include' | 'exclude';
+  surfaceSwitching?: 'include' | 'exclude';
+};
+
+export async function captureScreen(): Promise<ScreenshotResult> {
+  const canNative =
+    typeof navigator !== 'undefined' && Boolean(navigator.mediaDevices?.getDisplayMedia);
+
+  if (canNative) {
+    const native = await captureViaDisplayMedia();
+    if (native.status === 'ok') return { dataUrl: native.dataUrl, method: 'display-media' };
+    // The user explicitly dismissed the share picker → abort the whole report
+    // (do NOT silently fall back to a DOM capture).
+    if (native.status === 'cancelled') return { dataUrl: null, method: 'cancelled' };
+    // status === 'error' → the browser failed for another reason; fall through
+    // to the DOM capture below so the feature still works.
+  }
+
+  const dom = await captureViaHtmlToImage();
+  if (dom) return { dataUrl: dom, method: 'html-to-image' };
+
+  return { dataUrl: null, method: 'none' };
+}
+
+type NativeCaptureResult =
+  | { status: 'ok'; dataUrl: string }
+  | { status: 'cancelled' }
+  | { status: 'error' };
+
+async function captureViaDisplayMedia(): Promise<NativeCaptureResult> {
+  let stream: MediaStream | null = null;
+  try {
+    const options: ExtendedDisplayMediaOptions = {
+      video: { frameRate: 30 },
+      audio: false,
+      // Default the picker to the current tab and allow it to capture itself,
+      // so the flow is effectively one click.
+      preferCurrentTab: true,
+      selfBrowserSurface: 'include',
+      surfaceSwitching: 'exclude',
+    };
+    stream = await navigator.mediaDevices.getDisplayMedia(options);
+    const dataUrl = await grabFrame(stream);
+    return dataUrl ? { status: 'ok', dataUrl } : { status: 'error' };
+  } catch (err) {
+    // NotAllowedError / AbortError = the user dismissed the picker (Cancel).
+    if (
+      err instanceof DOMException &&
+      (err.name === 'NotAllowedError' || err.name === 'AbortError')
+    ) {
+      return { status: 'cancelled' };
+    }
+    return { status: 'error' };
+  } finally {
+    stream?.getTracks().forEach((track) => track.stop());
+  }
+}
+
+async function grabFrame(stream: MediaStream): Promise<string | null> {
+  const video = document.createElement('video');
+  video.srcObject = stream;
+  video.muted = true;
+  video.playsInline = true;
+
+  // Wait for metadata + playback to start (so videoWidth/Height are known).
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    video.onloadedmetadata = () => {
+      video.play().then(finish).catch(finish);
+    };
+    window.setTimeout(finish, 1500);
+  });
+
+  // Wait for an actually-painted frame before drawing — otherwise the canvas
+  // captures an empty frame (the original blank-screenshot bug).
+  await waitForPaintedFrame(video);
+
+  const width = video.videoWidth;
+  const height = video.videoHeight;
+  if (!width || !height) return null;
+
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return null;
+
+  // Draw FIRST, then tear the stream/source down. (Clearing srcObject before
+  // drawImage is what produced the blank capture previously.)
+  ctx.drawImage(video, 0, 0, width, height);
+  video.pause();
+  video.srcObject = null;
+
+  try {
+    return canvas.toDataURL('image/png');
+  } catch {
+    return null;
+  }
+}
+
+type VideoWithFrameCallback = HTMLVideoElement & {
+  requestVideoFrameCallback?: (callback: () => void) => number;
+};
+
+function waitForPaintedFrame(video: HTMLVideoElement): Promise<void> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    const withCallback = video as VideoWithFrameCallback;
+    if (typeof withCallback.requestVideoFrameCallback === 'function') {
+      withCallback.requestVideoFrameCallback(() => finish());
+      window.setTimeout(finish, 1000); // safety net
+    } else {
+      // Fallback: give the compositor a couple of frames to paint.
+      window.setTimeout(finish, 250);
+    }
+  });
+}
+
+/**
+ * The DOM fallback, supplied by the host.
+ *
+ * This used to `import('html-to-image')` behind a runtime-built specifier, so a
+ * host that never installed it would still build. That does not survive
+ * minification — the constant gets folded back into the import, Rollup sees a
+ * literal it cannot resolve, and the CONSUMER's build fails. A package cannot
+ * name a dependency it does not have.
+ *
+ * So the host injects it instead:
+ *
+ *   screenshotFallback: () => import('html-to-image').then((m) => m.toPng)
+ *
+ * Which is also more honest. getDisplayMedia handles the real cases and does it
+ * better — it captures cross-origin iframes, which no DOM renderer can reach —
+ * so this is a fallback for browsers without the Screen Capture API, and
+ * whether that is worth ~40 kB is the host's call, not ours.
+ */
+async function captureViaHtmlToImage(): Promise<string | null> {
+  const load = getConfig().screenshotFallback;
+  if (!load) return null;
+  const toPng = await load().catch(() => null);
+  if (!toPng) return null;
+  try {
+    return await toPng(document.body, {
+      cacheBust: true,
+      pixelRatio: Math.min(window.devicePixelRatio || 1, 2),
+      filter: (node: Node) =>
+        !(node instanceof HTMLElement && node.dataset?.debugReporter === 'true'),
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Shrink a screenshot to something the server will accept.
+ *
+ * A full-resolution PNG of a 4K screen is comfortably over 5 MB, and 5 MB is
+ * the per-file cap on the ingest endpoint — so an untouched capture is rejected
+ * at the moment the user presses send, after they have written the report and
+ * drawn on the image. The original ran every shot through
+ * `browser-image-compression` for exactly this reason.
+ *
+ * Done with a plain canvas instead, because a dependency to resize one image is
+ * not worth what every host app would pay for it. JPEG, not PNG: a screenshot
+ * is a photograph of a screen, and PNG's lossless promise costs several times
+ * the bytes to keep detail nobody is going to inspect.
+ */
+const MAX_EDGE = 2000;
+const QUALITY = 0.82;
+/** Comfortably under the 5 MB cap once base64 has added its third. */
+const TARGET_BYTES = 3_000_000;
+
+function loadImage(src: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error("could not read the screenshot"));
+    img.src = src;
+  });
+}
+
+export async function compressScreenshot(dataUrl: string): Promise<string> {
+  try {
+    const img = await loadImage(dataUrl);
+    const longest = Math.max(img.naturalWidth, img.naturalHeight);
+    const scale = Math.min(1, MAX_EDGE / longest);
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, Math.round(img.naturalWidth * scale));
+    canvas.height = Math.max(1, Math.round(img.naturalHeight * scale));
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return dataUrl;
+    // A white ground: JPEG has no alpha, and without this a transparent capture
+    // comes out on black.
+    ctx.fillStyle = "#fff";
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+    ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+
+    let quality = QUALITY;
+    let out = canvas.toDataURL("image/jpeg", quality);
+    // A dense screenshot can still be large at 2000px. Step down rather than
+    // send something that will be refused.
+    while (out.length > TARGET_BYTES && quality > 0.4) {
+      quality -= 0.15;
+      out = canvas.toDataURL("image/jpeg", quality);
+    }
+    return out;
+  } catch {
+    // Better a large screenshot the server might still take than none.
+    return dataUrl;
+  }
+}

package/src/signature.ts

@@ -0,0 +1,40 @@
+/**
+ * The dedup key: the failed API call that most likely caused the crash.
+ *
+ * `METHOD /path/:id STATUS`, e.g. `PUT /documents/:id 500`. Two users hitting
+ * the same broken endpoint produce the same key, so the backend merges their
+ * reports into one parent with duplicates under it — which is what stops an
+ * outage from arriving as forty separate tickets.
+ *
+ * The only normalisation is templating record ids out of the URL PATH, which is
+ * bounded, like a route pattern. No fuzzy text matching: a signature that merges
+ * two unrelated failures is worse than no signature, because the second report
+ * disappears under the first and nobody reads it.
+ *
+ * Returns null for a manual report or when there is no clear failure. We never
+ * guess — an unmerged ticket is a small cost, a wrongly merged one is a lost bug.
+ */
+import type { DebugBundle } from "./types";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NUMERIC = /^\d+$/;
+const LONG_HEX = /^[0-9a-f]{16,}$/i;
+
+export function errorSignature(bundle: DebugBundle): string | null {
+  if (bundle.reason.type === "manual") return null;
+  const failed = bundle.cause?.failedRequests?.[0];
+  if (!failed?.url) return null;
+
+  let path: string;
+  try {
+    path = new URL(failed.url, "http://x").pathname;
+  } catch {
+    path = failed.url;
+  }
+  const template = path
+    .split("/")
+    .map((seg) => (UUID.test(seg) || NUMERIC.test(seg) || LONG_HEX.test(seg) ? ":id" : seg))
+    .join("/");
+  const status = failed.status ?? (failed.error ? "ERR" : "?");
+  return `${failed.method ?? "REQ"} ${template} ${status}`;
+}