@lightworkai.official/debug-capture 0.6.0

package/dist/ui/strings.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The reporter's own words. Thai by default because that is who files these,
+ * with English for hosts that need it.
+ *
+ * Deliberately a flat map, not a translation framework: this is one dialog, and
+ * an i18n dependency in a package every host installs would be a tax on all of
+ * them for thirty strings.
+ */
+export interface Strings {
+    title: string;
+    summaryLabel: string;
+    summaryRequired: string;
+    summaryPlaceholder: string;
+    detailLabel: string;
+    detailPlaceholder: string;
+    annotateTitle: string;
+    annotateHint: string;
+    /** Footer of the standalone annotator dialog — NOT the reporter's own submit. */
+    annotateApply: string;
+    cancel: string;
+    toolRect: string;
+    toolArrow: string;
+    toolHighlight: string;
+    toolText: string;
+    deleteSelected: string;
+    clearAll: string;
+    annotateHelp: string;
+    capturing: string;
+    noScreenshot: string;
+    cancelled: string;
+    close: string;
+    submit: string;
+    submitting: string;
+    submitted: string;
+    crashed: string;
+    crashAction: string;
+    failed: string;
+    captured: string;
+    reporter: string;
+    page: string;
+}
+export declare function strings(locale: "th" | "en" | undefined): Strings;

package/dist/ui/styles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The dialog's stylesheet, as a string for the shadow root.
+ *
+ * A shadow root is the whole reason this is a custom element. The widget drops
+ * into apps we do not control, next to Tailwind or Bootstrap or Angular
+ * Material, and any of them would otherwise reach in and restyle it — or be
+ * restyled BY it. Inside a shadow root neither can happen, so there is no reset
+ * to fight, no specificity race, and no class-name prefix scheme to maintain.
+ *
+ * Everything is explicit for the same reason: the host's `body` font and colours
+ * do not inherit past the boundary, so stating them is not belt-and-braces.
+ */
+export declare const CSS = "\n:host { all: initial; }\n* { box-sizing: border-box; }\n\n.backdrop {\n  position: fixed; inset: 0; z-index: 2147483000;\n  display: flex; align-items: center; justify-content: center;\n  padding: 24px; background: rgba(15, 23, 42, 0.55);\n  font-family: system-ui, -apple-system, \"Segoe UI\", Roboto, \"Noto Sans Thai\", sans-serif;\n  color: #0f172a;\n}\n.panel {\n  display: flex; flex-direction: column; gap: 16px;\n  width: min(820px, 100%); max-height: 90vh; overflow-y: auto;\n  /* No bottom padding: the footer supplies its own and sits flush, so it can\n     stick to the panel's edge without a gap under it. */\n  padding: 24px 24px 0; border-radius: 16px; background: #fff;\n  box-shadow: 0 24px 60px rgba(15, 23, 42, 0.28);\n}\n.head { display: flex; align-items: flex-start; gap: 12px; }\nh2 { margin: 0; font-size: 20px; font-weight: 700; flex: 1; }\nlabel { display: block; font-size: 14px; font-weight: 600; margin-bottom: 6px; }\n.req { color: #dc2626; }\n.hint { font-weight: 400; color: #64748b; }\ninput[type=\"text\"], textarea {\n  width: 100%; padding: 10px 12px; font: inherit; font-size: 14px;\n  border: 1px solid #cbd5e1; border-radius: 10px; background: #fff; color: inherit;\n}\ninput[type=\"text\"]:focus, textarea:focus {\n  outline: none; border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.18);\n}\ntextarea { min-height: 88px; resize: vertical; }\n\n.meta {\n  padding: 12px 14px; border-radius: 10px; background: #f8fafc;\n  font-size: 13px; line-height: 1.7; color: #475569; word-break: break-all;\n}\n.meta b { color: #0f172a; font-weight: 600; }\n\n.tools { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }\n.sep { width: 1px; align-self: stretch; background: #e2e8f0; margin: 0 4px; }\nbutton {\n  display: inline-flex; align-items: center; gap: 6px; cursor: pointer;\n  padding: 8px 14px; font: inherit; font-size: 14px; font-weight: 500;\n  border: 1px solid #cbd5e1; border-radius: 10px; background: #fff; color: inherit;\n}\nbutton:hover:not(:disabled) { background: #f1f5f9; }\nbutton:disabled { opacity: 0.5; cursor: not-allowed; }\nbutton[aria-pressed=\"true\"] { border-color: #2563eb; background: #eff6ff; color: #1d4ed8; }\nbutton.primary { background: #2563eb; border-color: #2563eb; color: #fff; }\nbutton.primary:hover:not(:disabled) { background: #1d4ed8; }\nbutton.icon { padding: 6px 10px; border-color: transparent; font-size: 18px; line-height: 1; }\n\n/* The on-image text editor. Absolutely placed over the canvas and matched to\n   the shape it becomes \u2014 same weight, same red, same white plate \u2014 so what you\n   type is what gets drawn, at the position you clicked. Sized in JS, because\n   the font size tracks the image's own scale. */\n.text-edit {\n  position: absolute; z-index: 2; margin: 0; padding: 2px 4px;\n  font-family: system-ui, sans-serif; font-weight: 600; line-height: 1.25;\n  color: #e11d48; background: rgba(255, 255, 255, 0.92);\n  border: 1px dashed #e11d48; border-radius: 4px; outline: none;\n  box-shadow: 0 2px 10px rgba(15, 23, 42, 0.18);\n}\n.text-edit::placeholder { color: rgba(225, 29, 72, 0.45); }\n\ncanvas { width: 100%; height: auto; display: block; border: 1px solid #e2e8f0; border-radius: 10px; touch-action: none; }\n.shot { position: relative; }\n.status { font-size: 13px; color: #64748b; }\n.status[data-tone=\"error\"] { color: #dc2626; }\n/* Pinned to the bottom of the scrolling panel.\n   A screenshot is tall \u2014 often taller than the viewport \u2014 so \u0E41\u0E08\u0E49\u0E07\u0E1B\u0E31\u0E0D\u0E2B\u0E32 sat\n   below the fold and the last step of filing a report was \"scroll to the end\n   and find the button\". Sticky, with its own ground and a rule above it so the\n   annotated image scrolls underneath rather than bleeding into it. */\n.foot {\n  position: sticky; bottom: 0; z-index: 3;\n  display: flex; align-items: center; gap: 12px;\n  margin: 4px -24px 0; padding: 12px 24px;\n  background: #fff; border-top: 1px solid #e2e8f0;\n  border-radius: 0 0 16px 16px;\n}\n.foot .grow { flex: 1; }\n";

package/dist/ui/toast.d.ts

@@ -0,0 +1,11 @@
+export interface ToastAction {
+    label: string;
+    /**
+     * Runs inside the click, so it can open screen capture. That is the whole
+     * point of offering a crash as a toast with a button rather than opening the
+     * reporter on its own: a browser grants capture to a real click and nothing
+     * else.
+     */
+    onClick: () => void;
+}
+export declare function showToast(message: string, tone?: "success" | "error", action?: ToastAction): void;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@lightworkai.official/debug-capture",
+  "version": "0.6.0",
+  "description": "Report-a-problem widget: rolling network/console/action capture, annotated screenshot, and submission to a Lightwork Support host",
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./embed": "./dist/debug-capture.js",
+    "./style.css": "./src/styles.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun run build:esm && bun run build:iife && bun run build:types",
+    "build:esm": "bun build src/index.ts --outfile dist/index.mjs --format esm --minify",
+    "build:iife": "bun build src/embed.ts --outfile dist/debug-capture.js --format iife --minify",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test src"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "happy-dom": "^20.14.0",
+    "typescript": "^5.6.0"
+  },
+  "main": "./dist/index.mjs",
+  "keywords": [
+    "bug-report",
+    "debug",
+    "screenshot",
+    "network-capture",
+    "console-capture",
+    "support",
+    "helpdesk",
+    "ticket",
+    "annotate"
+  ],
+  "license": "MIT",
+  "author": "Lightwork AI",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/budget.ts

@@ -0,0 +1,62 @@
+/**
+ * Keeping a bundle inside what the server will accept.
+ *
+ * The capture buffers hold full response bodies, which is the point — a 500's
+ * body is usually the answer. But a long session can hold megabytes of them, and
+ * the ingest endpoint caps an attachment at 5 MB and the request at 10 MB total.
+ * Arriving over the limit means the report is refused at the very moment
+ * somebody finally bothered to file one.
+ *
+ * So trim, in the order that loses the least: response bodies are the biggest
+ * and least often needed, oldest first, because the failure that prompted the
+ * report is at the END of the buffer. Only if that is not enough do whole
+ * entries go, and the trail of actions is never touched — it is small, and it is
+ * the part a human actually reads.
+ */
+import type { DebugBundle, CapturedRequest } from "./types";
+
+/**
+ * Well under the 5 MB attachment cap. The gap is deliberate: base64 adds a
+ * third, and the screenshot is in the same request.
+ */
+export const BUNDLE_BUDGET_BYTES = 2_000_000;
+
+const OMITTED = "[body dropped — report size budget]";
+
+function sizeOf(bundle: DebugBundle): number {
+  // The screenshot is a separate attachment; measuring it here would trim
+  // bodies to make room for something that is not in this budget.
+  const { screenshotDataUrl: _omit, ...rest } = bundle;
+  return JSON.stringify(rest).length;
+}
+
+export function trimToBudget(bundle: DebugBundle, budget = BUNDLE_BUDGET_BYTES): DebugBundle {
+  if (sizeOf(bundle) <= budget) return bundle;
+
+  // Copy before mutating: the buffers are live and the user may file again.
+  const network: CapturedRequest[] = bundle.network.map((r) => ({ ...r }));
+  const out: DebugBundle = { ...bundle, network };
+
+  // Oldest first — the request that broke things is the most recent one.
+  for (const entry of network) {
+    if (sizeOf(out) <= budget) return out;
+    if (typeof entry.responseSnippet === "string" && entry.responseSnippet.length > OMITTED.length) {
+      entry.responseSnippet = OMITTED;
+    }
+    if (typeof entry.requestBody === "string" && entry.requestBody.length > OMITTED.length) {
+      entry.requestBody = OMITTED;
+    }
+  }
+
+  // Still too big: drop whole requests from the oldest end. Keep the newest,
+  // which is where the failure is.
+  while (out.network.length > 1 && sizeOf(out) > budget) {
+    out.network = out.network.slice(1);
+  }
+
+  // Console last, same reasoning.
+  while (out.console.length > 1 && sizeOf(out) > budget) {
+    out.console = out.console.slice(1);
+  }
+  return out;
+}

package/src/bundle.ts

@@ -0,0 +1,274 @@
+// Bundle assembly + output. Turns the collected context/cause/actions/network/
+// console/screenshot into a Markdown report — for the clipboard, and as the
+// human-readable half of what gets filed.
+//
+// The original also built a .zip for download. That was a second delivery path
+// for people who could not reach the ticket system; ours submits directly, so
+// the zip (and JSZip with it) is gone rather than shipped unused.
+// + curl/console/steps logs.
+
+import { actionCountSuffix, getActionTrail } from './capture/actionTrail';
+import { causeCount, computeCause } from './capture/cause';
+import { getConsoleLog } from './capture/consoleBuffer';
+import { collectContext } from './context';
+import { getNetworkLog } from './capture/networkBuffer';
+import type {
+  ActionTrailEntry,
+  CapturedConsoleEntry,
+  CapturedRequest,
+  CauseSummary,
+  DebugBundle,
+  DebugReason,
+  ErroredQuery,
+  ScreenshotMethod,
+} from './types';
+
+const SCHEMA_VERSION = 2;
+
+const REASON_LABELS: Record<DebugReason['type'], string> = {
+  manual: 'ผู้ใช้แจ้งเอง',
+  'runtime-error': 'ข้อผิดพลาด runtime (auto)',
+  unhandledrejection: 'Promise rejection (auto)',
+  'framework-error': 'หน้าจอค้าง/พัง (auto)',
+};
+
+export interface BuildBundleInput {
+  note: string;
+  reason: DebugReason;
+  screenshotDataUrl: string | null;
+  screenshotMethod: ScreenshotMethod;
+  erroredQueries: ErroredQuery[];
+}
+
+/** Snapshot the live buffers + context into an immutable bundle. */
+export function buildBundle(input: BuildBundleInput): DebugBundle {
+  const network = getNetworkLog();
+  const consoleLog = getConsoleLog();
+  return {
+    context: collectContext(),
+    reason: input.reason,
+    note: input.note,
+    cause: computeCause(network, consoleLog, input.erroredQueries),
+    actionTrail: getActionTrail(),
+    network,
+    console: consoleLog,
+    screenshotDataUrl: input.screenshotDataUrl,
+    screenshotMethod: input.screenshotMethod,
+    meta: {
+      generatedBy: 'lightwork-debug-capture',
+      schemaVersion: SCHEMA_VERSION,
+    },
+  };
+}
+
+function escapeSingleQuotes(value: string): string {
+  return value.replace(/'/g, `'\\''`);
+}
+
+export function toCurl(req: CapturedRequest): string {
+  const parts = [`curl -X ${req.method} '${req.url}'`];
+  for (const [key, value] of Object.entries(req.requestHeaders)) {
+    parts.push(`  -H '${key}: ${escapeSingleQuotes(value)}'`);
+  }
+  if (req.requestBody) {
+    parts.push(`  --data '${escapeSingleQuotes(req.requestBody)}'`);
+  }
+  return parts.join(' \\\n');
+}
+
+function reqStatus(req: CapturedRequest): string {
+  if (req.error) return `ERR ${req.error}`;
+  return `${req.status ?? '—'} ${req.statusText ?? ''}`.trim();
+}
+
+function networkToText(requests: CapturedRequest[]): string {
+  if (requests.length === 0) return 'No network activity captured.';
+  return requests
+    .map((req) => {
+      const dur = req.durationMs != null ? `${req.durationMs}ms` : '—';
+      const header = `# [${reqStatus(req)}] ${req.method} ${req.url}  (${dur}, ${req.startedAt})`;
+      const snippet = req.responseSnippet ? `\n# response: ${req.responseSnippet}` : '';
+      return `${header}\n${toCurl(req)}${snippet}`;
+    })
+    .join('\n\n');
+}
+
+function consoleToText(entries: CapturedConsoleEntry[]): string {
+  if (entries.length === 0) return 'No console output captured.';
+  return entries
+    .map((entry) => `[${entry.at}] ${entry.level.toUpperCase()}: ${entry.message}`)
+    .join('\n');
+}
+
+function stepsToText(entries: ActionTrailEntry[]): string {
+  if (entries.length === 0) return 'No user actions captured.';
+  // Numbering counts only the reporter's OWN actions, so the numbered lines are
+  // exactly the steps to repeat. App reactions (a dialog opening, a toast) are
+  // indented underneath as "↳" — what should happen back, not a step to redo.
+  let actionNo = 0;
+  return entries
+    .map((entry) => {
+      const src = entry.source ? `  (${entry.source})` : '';
+      const label = `${entry.detail}${actionCountSuffix(entry.count)}${src}`;
+      if (entry.kind === 'ui') return `   ↳ [${entry.at}] ${label}`;
+      actionNo += 1;
+      const line = `${actionNo}. [${entry.at}] ${label}`;
+      // The control's state flip after the click — the difference between
+      // "pressed บันทึก" and "pressed บันทึก and it went into loading".
+      return entry.afterNote ? `${line}\n   ↳ ${entry.afterNote}` : line;
+    })
+    .join('\n');
+}
+
+function causeToLines(cause: CauseSummary): string[] {
+  const lines: string[] = [];
+  for (const req of cause.failedRequests) {
+    lines.push(`✗ ${req.status ?? req.error ?? 'ERR'}  ${req.method} ${req.url}`);
+  }
+  for (const err of cause.errors) lines.push(`⚠ ${err}`);
+  for (const query of cause.erroredQueries) lines.push(`⚠ React Query error: ${query.key} — ${query.error}`);
+  return lines;
+}
+
+function summaryLines(bundle: DebugBundle): string[] {
+  const { context: ctx } = bundle;
+  return [
+    `User      : ${ctx.user.fullName ?? '—'} (${ctx.user.email ?? '—'})`,
+    `Unit      : ${ctx.user.unit ?? '—'}`,
+    `Roles     : ${ctx.user.roles?.join(', ') || '—'}`,
+    `Route     : ${ctx.route.href}`,
+    `Module    : ${ctx.module ? `${ctx.module.label} (${ctx.module.key})` : "—"}`,
+    `App       : ${ctx.app.name} v${ctx.app.version} · ${ctx.app.environment}`,
+    `Memory    : ${ctx.performance.memoryUsedMb ?? '—'}/${ctx.performance.memoryLimitMb ?? '—'} MB`,
+    `Client    : ${ctx.client.userAgent}`,
+    `Viewport  : ${ctx.client.viewport.width}×${ctx.client.viewport.height} @${ctx.client.viewport.dpr}x`,
+    `Reason    : ${REASON_LABELS[bundle.reason.type]}${bundle.reason.message ? ` — ${bundle.reason.message}` : ''}`,
+    `Captured  : ${bundle.network.length} requests · ${bundle.console.length} console · ${bundle.actionTrail.length} actions · screenshot=${bundle.screenshotMethod}`,
+  ];
+}
+
+/** Ticket-friendly Markdown report (excludes the screenshot binary). */
+export function bundleToMarkdown(bundle: DebugBundle): string {
+  const cause = causeToLines(bundle.cause);
+  const md: string[] = [
+    `## 🐞 ${bundle.context.app.name} — Debug Report`,
+    `**Generated:** ${bundle.context.capturedAt}`,
+    '',
+    ...summaryLines(bundle).map((line) => `- ${line.replace(/\s{2,}:/, ':')}`),
+    '',
+    `**หมายเหตุจากผู้แจ้ง:** ${bundle.note.trim() || '(ไม่มี)'}`,
+  ];
+
+  if (cause.length > 0) {
+    md.push('', '### ⚠ สาเหตุที่น่าจะเป็น', '```', ...cause, '```');
+  }
+
+  md.push(
+    '',
+    `<details><summary>ขั้นตอน (${bundle.actionTrail.length})</summary>`,
+    '',
+    '```',
+    stepsToText(bundle.actionTrail),
+    '```',
+    '</details>',
+    '',
+    `<details><summary>Network (${bundle.network.length})</summary>`,
+    '',
+    '```',
+    networkToText(bundle.network),
+    '```',
+    '</details>',
+    '',
+    `<details><summary>Console (${bundle.console.length})</summary>`,
+    '',
+    '```',
+    consoleToText(bundle.console),
+    '```',
+    '</details>',
+    '',
+    '_ข้อมูลลับ (token, cookie) ถูกปกปิดอัตโนมัติ · ภาพหน้าจออยู่ในไฟล์ .zip_',
+  );
+  return md.join('\n');
+}
+
+function readmeText(bundle: DebugBundle): string {
+  return [
+    `🐞 ${bundle.context.app.name} — Debug Report`,
+    `Generated: ${bundle.context.capturedAt}`,
+    '',
+    ...summaryLines(bundle),
+    '',
+    `Note: ${bundle.note.trim() || '(none)'}`,
+    '',
+    'Files:',
+    `- screenshot.png    Screenshot at time of report (method: ${bundle.screenshotMethod})`,
+    '- report.md         Ticket-friendly Markdown report',
+    '- report.json       Full structured bundle (machine-readable)',
+    '- steps.txt         Recent user actions (steps to reproduce)',
+    '- network.curl.txt  Recent requests as reproducible curl commands',
+    '- console.log.txt   Recent console output + uncaught errors',
+    '',
+    'Secrets (authorization headers, cookies, token query params) are redacted.',
+  ].join('\n');
+}
+
+/** `2026-08-10_17-42-05` — sortable, and safe in a filename on every platform. */
+function fileStamp(iso: string): string {
+  return iso.replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+}
+
+export function bundleFileName(bundle: DebugBundle, ext: string): string {
+  return `debug-report_${fileStamp(bundle.context.capturedAt)}.${ext}`;
+}
+
+export function hasCause(bundle: DebugBundle): boolean {
+  return causeCount(bundle.cause) > 0;
+}
+
+export function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  window.setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+/** Copy a PNG data URL to the clipboard as an actual image (pasteable into
+ *  chat apps), not as base64 text. */
+export async function copyImageToClipboard(dataUrl: string): Promise<boolean> {
+  if (!navigator.clipboard || typeof ClipboardItem === 'undefined') return false;
+  try {
+    const blob = await (await fetch(dataUrl)).blob();
+    await navigator.clipboard.write([new ClipboardItem({ [blob.type || 'image/png']: blob })]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function copyTextToClipboard(text: string): Promise<boolean> {
+  try {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+    // fall through to legacy path
+  }
+  try {
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+    const ok = document.execCommand('copy');
+    textarea.remove();
+    return ok;
+  } catch {
+    return false;
+  }
+}