@lightworkai.official/debug-capture-react 0.6.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lightworkai.official/debug-capture-react",
+  "version": "0.6.0",
+  "description": "React bindings for @lightworkai.official/debug-capture",
+  "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"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outfile dist/index.mjs --format esm --external react --external react/jsx-runtime --external @tiptap/react --external @tiptap/starter-kit --external @tiptap/extension-image --external @tiptap/extension-placeholder --external @lightworkai.official/debug-capture && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "@lightworkai.official/debug-capture": "^0.6.0",
+    "@tiptap/react": "^3",
+    "@tiptap/starter-kit": "^3",
+    "@tiptap/extension-image": "^3",
+    "@tiptap/extension-placeholder": "^3"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.6.0"
+  },
+  "main": "./dist/index.mjs",
+  "keywords": [
+    "react",
+    "bug-report",
+    "debug",
+    "screenshot",
+    "support",
+    "helpdesk"
+  ],
+  "license": "MIT",
+  "author": "Lightwork AI",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/DebugCaptureInit.tsx

@@ -0,0 +1,56 @@
+/**
+ * Arms the capture buffers and mounts the reporter. Renders nothing.
+ *
+ * Put it once in the root layout, above the routes — the buffers need to be
+ * recording BEFORE a user hits a problem. A report opened from a page that only
+ * just started listening has no trail of how the user got there, which is the
+ * half that makes a report reproducible.
+ */
+import { useEffect } from "react";
+import {
+  configureDebugCapture,
+  installDebugCapture,
+  isConfigured,
+  setErroredQueriesSource,
+  type DebugCaptureConfig,
+  type ErroredQuery,
+  type InstallOptions,
+} from "@lightworkai.official/debug-capture";
+
+export interface DebugCaptureInitProps extends InstallOptions {
+  /**
+   * The config. Pass it here rather than calling `configureDebugCapture`
+   * yourself from a parent's effect — React runs CHILD effects before parent
+   * ones, so a parent that configures in `useEffect` runs *after* this
+   * component has already tried to install, and capture never arms.
+   *
+   * Calling `configureDebugCapture` at module scope also works, and is what the
+   * README shows. This exists so the wrong order is not reachable.
+   */
+  config?: DebugCaptureConfig;
+  /**
+   * Failed queries from the app's data layer, if it has one. A callback so this
+   * package never depends on react-query or any other client — with TanStack
+   * Query that is:
+   *
+   *   errorQueries={() =>
+   *     queryClient.getQueryCache().findAll()
+   *       .filter((q) => q.state.status === 'error')
+   *       .map((q) => ({ key: JSON.stringify(q.queryKey), error: String(q.state.error) }))}
+   */
+  errorQueries?: () => ErroredQuery[];
+}
+
+export function DebugCaptureInit({ config, errorQueries, ...options }: DebugCaptureInitProps): null {
+  // Before the effect, not inside it: an effect runs after the first paint, and
+  // anything the app fetched or logged in between would be missed.
+  if (config && !isConfigured()) configureDebugCapture(config);
+
+  useEffect(() => {
+    if (errorQueries) setErroredQueriesSource(errorQueries);
+    installDebugCapture(options);
+    // install is idempotent and app-wide; re-running it when a prop changes
+    // would cost a render and do nothing, so the deps stay empty on purpose.
+  }, []);
+  return null;
+}

package/src/DebugErrorBoundary.tsx

@@ -0,0 +1,50 @@
+/**
+ * Catches a render crash and offers to report it.
+ *
+ * A React render error does NOT reach window.onerror, so the crash watcher in
+ * the core never sees it — this is the only way those get captured at all, and
+ * they are the ones users describe as "the screen went white".
+ *
+ * Class component because that is the only thing React gives us:
+ * componentDidCatch has no hook equivalent.
+ */
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import { emitCrashFromBoundary } from "./crash";
+
+interface Props {
+  children: ReactNode;
+  /** What to show instead of the crashed subtree. */
+  fallback?: (error: Error, report: () => void) => ReactNode;
+}
+
+interface State {
+  error: Error | null;
+}
+
+export class DebugErrorBoundary extends Component<Props, State> {
+  override state: State = { error: null };
+
+  static getDerivedStateFromError(error: Error): State {
+    return { error };
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    emitCrashFromBoundary(error, info.componentStack ?? undefined);
+  }
+
+  override render(): ReactNode {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    // No default UI beyond the report action: what a crashed screen should look
+    // like is the host's decision, and ours would be wrong in their layout.
+    return this.props.fallback?.(error, () => reportBoundaryError(error)) ?? null;
+  }
+}
+
+function reportBoundaryError(error: Error): void {
+  // Imported lazily so the boundary module does not pull the reporter into a
+  // chunk that every page loads.
+  void import("@lightworkai.official/debug-capture").then(({ launch }) =>
+    launch({ type: "framework-error", message: error.message, stack: error.stack }),
+  );
+}

package/src/ReportProblemButton.tsx

@@ -0,0 +1,79 @@
+/**
+ * The bug icon that opens the reporter.
+ *
+ * `launch` runs straight out of the click with nothing awaited in front of it.
+ * That is not style: screen capture is gated on a user gesture, and a single
+ * await between the click and `getDisplayMedia` loses it — the browser then
+ * refuses with an error that says nothing about why.
+ *
+ * It arrives presentable and `className` replaces that entirely. Shipping it
+ * unstyled meant every host wrote the same forty characters of CSS to make a
+ * bug icon look like a header button — work the library should have done. But
+ * the default must be *replaceable*, not merged: a widget with opinions about
+ * its border radius that you cannot override is a widget somebody has to fight.
+ */
+import type { ButtonHTMLAttributes, CSSProperties, ReactNode } from "react";
+import { launch } from "@lightworkai.official/debug-capture";
+
+export interface ReportProblemButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Replace the default bug glyph — pass the host's own icon component. */
+  children?: ReactNode;
+  label?: string;
+}
+
+/**
+ * A square icon button that sits in a header without looking out of place, in
+ * inline styles so it needs no stylesheet and no build step. Passing
+ * `className` drops all of it — a host with a design system wants its own
+ * button, not ours with theirs layered on top.
+ */
+const DEFAULT_STYLE: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  width: 38,
+  height: 38,
+  padding: 0,
+  border: "none",
+  borderRadius: 8,
+  background: "transparent",
+  color: "currentColor",
+  cursor: "pointer",
+};
+
+const BUG = (
+  <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    <path d="M8 2l1.9 1.9M16 2l-1.9 1.9" />
+    <rect x="8" y="6" width="8" height="14" rx="4" />
+    <path d="M3 13h5M16 13h5M4 8l3 2M20 8l-3 2M4 18l3-2M20 18l-3-2" />
+  </svg>
+);
+
+export function ReportProblemButton({
+  children,
+  label = "รายงานปัญหา",
+  className,
+  style,
+  onClick,
+  ...rest
+}: ReportProblemButtonProps) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      className={className}
+      // Pulled out of the spread deliberately: `{...rest}` after this would put
+      // the caller's undefined `style` back over the default and undo it.
+      style={className ? style : { ...DEFAULT_STYLE, ...style }}
+      {...rest}
+      onClick={(event) => {
+        onClick?.(event);
+        if (event.defaultPrevented) return;
+        launch({ type: "manual" });
+      }}
+    >
+      {children ?? BUG}
+    </button>
+  );
+}

package/src/components/ImageAnnotatorDialog.tsx

@@ -0,0 +1,160 @@
+/**
+ * Draw on an image before it is sent.
+ *
+ * The original opens this the moment you pick a picture, and the reason is in
+ * its own comment: annotating BEFORE upload keeps the canvas same-origin, so
+ * `toDataURL` is not tainted by a cross-origin presigned URL. Pointing at the
+ * problem is also most of what a screenshot is for.
+ *
+ * The drawing itself is `createAnnotator` from the core — one canvas engine,
+ * shared by all three framework packages, because there is no declarative way
+ * to draw on a canvas. What is here is only the chrome.
+ */
+import { useEffect, useRef, useState } from "react";
+import {
+  createAnnotator,
+  reporterStrings,
+  type Annotator,
+  type AnnotatorTool,
+  type ReporterStrings,
+} from "@lightworkai.official/debug-capture";
+import { ArrowUpRightIcon, HighlighterIcon, SquareIcon, TrashIcon, TypeIcon } from "./icons";
+
+const TOOLS: { tool: AnnotatorTool; key: keyof ReporterStrings; Icon: typeof SquareIcon }[] = [
+  { tool: "rect", key: "toolRect", Icon: SquareIcon },
+  { tool: "arrow", key: "toolArrow", Icon: ArrowUpRightIcon },
+  { tool: "highlight", key: "toolHighlight", Icon: HighlighterIcon },
+  { tool: "text", key: "toolText", Icon: TypeIcon },
+];
+
+export interface ImageAnnotatorDialogProps {
+  /** The picked image, as a same-origin data URI. */
+  src: string;
+  /** Shown in the description, as the app's dialog does. */
+  filename?: string;
+  locale: "th" | "en" | undefined;
+  /** The annotated image, at full resolution. */
+  onConfirm: (dataUri: string) => void;
+  onCancel: () => void;
+}
+
+export function ImageAnnotatorDialog({ src, filename, locale, onConfirm, onCancel }: ImageAnnotatorDialogProps) {
+  const t = reporterStrings(locale);
+  const canvas = useRef<HTMLCanvasElement>(null);
+  // A ref, not state: the annotator holds a canvas and its own mutable state,
+  // and none of that should drive a render.
+  const annotator = useRef<Annotator | null>(null);
+  const [active, setActive] = useState<AnnotatorTool | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const node = canvas.current;
+    if (!node) return;
+    const image = new Image();
+    image.addEventListener("load", () => {
+      // A backing store at the image's own size, BEFORE the annotator draws
+      // into it. Without this the canvas keeps its default 300x150, the image
+      // is squashed into that, and CSS then stretches the result — blurry, and
+      // the wrong shape.
+      node.width = image.naturalWidth;
+      node.height = image.naturalHeight;
+      annotator.current = createAnnotator(node, image, () => {
+        // The toolbar mirrors the engine, so it has to hear about a tool being
+        // CONSUMED as well as a shape being added.
+        setActive(null);
+      });
+      setLoading(false);
+    });
+    image.src = src;
+    return () => {
+      annotator.current?.destroy();
+      annotator.current = null;
+    };
+  }, [src]);
+
+  function pick(tool: AnnotatorTool): void {
+    const next = active === tool ? null : tool;
+    setActive(next);
+    annotator.current?.setTool(next);
+  }
+
+  return (
+    <div
+      className="lw-annotator"
+      role="dialog"
+      aria-modal="true"
+      onClick={(event) => {
+        if (event.target === event.currentTarget) onCancel();
+      }}
+    >
+      {/* Header, toolbar, canvas, help, footer — the same shape and the same
+          words as the app's own dialog, so the two are one thing in two places
+          rather than two things that resemble each other. */}
+      <div className="lw-annotator__panel">
+        <div className="lw-annotator__head">
+          <div className="lw-grow">
+            <h2 className="lw-annotator__title">{t.annotateTitle}</h2>
+            <p className="lw-annotator__desc">
+              {t.annotateHint}
+              {filename ? ` · ${filename}` : ""}
+            </p>
+          </div>
+          <button type="button" className="lw-annotator__close" aria-label={t.cancel} onClick={onCancel}>
+            ✕
+          </button>
+        </div>
+
+        <div className="lw-annotator__tools">
+          {TOOLS.map(({ tool, key, Icon }) => (
+            <button
+              key={tool}
+              type="button"
+              className="lw-atool"
+              aria-pressed={active === tool}
+              disabled={loading}
+              onClick={() => pick(tool)}
+            >
+              <Icon /> {t[key] as string}
+            </button>
+          ))}
+          <span className="lw-grow" />
+          {/* Right-aligned and on its own, like the app's. Deleting ONE shape is
+              the ✕ on the shape, which is what the help line below explains. */}
+          <button
+            type="button"
+            className="lw-atool lw-atool--plain"
+            disabled={loading}
+            onClick={() => {
+              annotator.current?.clear();
+              setActive(null);
+            }}
+          >
+            <TrashIcon /> {t.clearAll}
+          </button>
+        </div>
+
+        <div className="lw-annotator__canvas">
+          <div className="lw-annotator__canvasbox">
+            <canvas ref={canvas} />
+          </div>
+        </div>
+
+        <p className="lw-annotator__hint">{t.annotateHelp}</p>
+
+        <div className="lw-annotator__actions">
+          <span className="lw-grow" />
+          <button type="button" className="lw-btn" onClick={onCancel}>{t.cancel}</button>
+          <button
+            type="button"
+            className="lw-send"
+            disabled={loading}
+            // Full resolution, never the on-screen scale.
+            onClick={() => onConfirm(annotator.current?.toDataUrl() ?? src)}
+          >
+            {t.annotateApply}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}