@ozsarman/clarityjs 0.6.0

package/src/error-overlay.js

@@ -0,0 +1,535 @@
+/**
+ * Clarity.js — Developer Error Overlay
+ *
+ * A fullscreen Shadow DOM overlay that surfaces:
+ *   - Compiler errors (from the Clarity Vite plugin)
+ *   - Runtime errors (window.onerror / unhandledrejection)
+ *   - Manually reported errors (_overlayShowError)
+ *
+ * The overlay is completely isolated from page styles via Shadow DOM and
+ * renders zero bytes in production builds (guard with import.meta.env.DEV).
+ *
+ * Integration:
+ *   import { initErrorOverlay } from '@ozsarman/clarityjs/error-overlay';
+ *   if (import.meta.env.DEV) initErrorOverlay();
+ *
+ * Vite plugin usage:
+ *   The clarity Vite plugin (vite-plugin.js) calls
+ *   `_overlayShowError({ message, file, line, col, frame, type })` over the
+ *   Vite HMR WebSocket when a .clarity file fails to compile.
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+// ─── Public surface ───────────────────────────────────────────────────────────
+
+let _overlay = null;
+
+/**
+ * Mount the error overlay. Safe to call multiple times — only one instance
+ * is created.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.catchRuntime=true]   Listen for window.onerror / unhandledrejection
+ * @param {boolean} [options.catchHMR=true]       Listen for Vite HMR error events
+ * @returns {{ dismiss: () => void, show: _overlayShowError }}
+ */
+export function initErrorOverlay({ catchRuntime = true, catchHMR = true } = {}) {
+  if (typeof document === 'undefined') return { dismiss: () => {}, show: () => {} };
+  if (_overlay) return { dismiss: () => _overlay?.dismiss(), show: _overlayShowError };
+
+  _overlay = new ErrorOverlay();
+
+  // ── Runtime error listeners ───────────────────────────────────────────────
+  if (catchRuntime) {
+    _overlay._stopRuntime = _listenRuntime();
+  }
+
+  // ── Vite HMR listeners ────────────────────────────────────────────────────
+  if (catchHMR) {
+    _overlay._stopHMR = _listenHMR();
+  }
+
+  return {
+    dismiss: () => _overlay?.dismiss(),
+    show:    _overlayShowError,
+  };
+}
+
+/**
+ * Programmatically show an error in the overlay.
+ *
+ * @param {object} err
+ * @param {string}  err.message   - Human-readable error message
+ * @param {'compiler'|'runtime'|'network'} [err.type='runtime']
+ * @param {string}  [err.file]    - Source file path
+ * @param {number}  [err.line]    - 1-based line number
+ * @param {number}  [err.col]     - 1-based column number
+ * @param {string}  [err.frame]   - Code frame snippet (pre-formatted)
+ * @param {string}  [err.stack]   - Error stack trace string
+ * @param {string}  [err.plugin]  - Plugin/module name that produced the error
+ */
+export function _overlayShowError(err) {
+  if (!_overlay) return;
+  _overlay.push(err);
+}
+
+/**
+ * Dismiss the overlay (same as clicking the close button).
+ */
+export function _overlayDismiss() {
+  _overlay?.dismiss();
+}
+
+// ─── Runtime listener ─────────────────────────────────────────────────────────
+
+function _listenRuntime() {
+  function onError(event) {
+    const e = event.error ?? event;
+    _overlayShowError({
+      type:    'runtime',
+      message: e?.message ?? String(event.message ?? event),
+      file:    event.filename ?? e?.fileName,
+      line:    event.lineno   ?? e?.lineNumber,
+      col:     event.colno    ?? e?.columnNumber,
+      stack:   e?.stack,
+    });
+    // Don't swallow — let the browser console also log it
+  }
+
+  function onUnhandled(event) {
+    const reason = event.reason;
+    _overlayShowError({
+      type:    'runtime',
+      message: reason instanceof Error ? reason.message : String(reason ?? 'Unhandled Promise rejection'),
+      stack:   reason instanceof Error ? reason.stack : undefined,
+    });
+  }
+
+  window.addEventListener('error',              onError,     true);
+  window.addEventListener('unhandledrejection', onUnhandled, true);
+
+  return () => {
+    window.removeEventListener('error',              onError,     true);
+    window.removeEventListener('unhandledrejection', onUnhandled, true);
+  };
+}
+
+// ─── Vite HMR listener ────────────────────────────────────────────────────────
+
+function _listenHMR() {
+  // Vite exposes import.meta.hot in dev mode
+  if (typeof import.meta === 'undefined' || !import.meta.hot) return () => {};
+
+  // Vite's built-in error event — fires for plugin transform errors
+  import.meta.hot.on('vite:error', (data) => {
+    const err = data.err ?? data;
+    _overlayShowError({
+      type:    'compiler',
+      message: err.message ?? String(err),
+      file:    err.id ?? err.file,
+      line:    err.loc?.line,
+      col:     err.loc?.column,
+      frame:   err.frame,
+      plugin:  err.plugin,
+      stack:   err.stack,
+    });
+  });
+
+  // Custom Clarity compiler error channel
+  import.meta.hot.on('clarity:error', (data) => {
+    _overlayShowError({ type: 'compiler', ...data });
+  });
+
+  // Clear overlay when HMR replaces the module successfully
+  import.meta.hot.on('vite:afterUpdate', () => {
+    _overlay?.clearAll();
+  });
+
+  return () => {}; // Vite HMR listeners can't be removed individually
+}
+
+// ─── ErrorOverlay class ───────────────────────────────────────────────────────
+
+class ErrorOverlay {
+  constructor() {
+    /** @type {Array<object>} */
+    this._errors = [];
+    this._currentIndex = 0;
+    this._stopRuntime = null;
+    this._stopHMR     = null;
+
+    this.el = document.createElement('div');
+    this.el.setAttribute('data-clarity-error-overlay', '');
+    Object.assign(this.el.style, {
+      position: 'fixed',
+      inset: '0',
+      zIndex: '2147483647',
+      display: 'none',
+    });
+
+    const shadow = this.el.attachShadow({ mode: 'open' });
+    const style = document.createElement('style');
+    style.textContent = _CSS;
+    shadow.appendChild(style);
+
+    this._root = document.createElement('div');
+    this._root.className = 'overlay';
+    shadow.appendChild(this._root);
+
+    document.body.appendChild(this.el);
+    this._buildShell();
+  }
+
+  // ── Public ─────────────────────────────────────────────────────────────────
+
+  push(err) {
+    this._errors.push(_normalizeError(err));
+    // Jump to the newest error
+    this._currentIndex = this._errors.length - 1;
+    this.el.style.display = '';
+    this._render();
+  }
+
+  dismiss() {
+    this.el.style.display = 'none';
+    this._errors = [];
+    this._currentIndex = 0;
+  }
+
+  clearAll() {
+    this.dismiss();
+  }
+
+  dispose() {
+    this._stopRuntime?.();
+    this._stopHMR?.();
+    this.el.remove();
+    _overlay = null;
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  _buildShell() {
+    this._root.innerHTML = `
+      <div class="backdrop"></div>
+      <div class="card">
+        <div class="card-header">
+          <span class="badge badge--compiler hidden" id="badge-compiler">Compiler</span>
+          <span class="badge badge--runtime hidden" id="badge-runtime">Runtime</span>
+          <span class="badge badge--network hidden" id="badge-network">Network</span>
+          <span class="title" id="err-title">Error</span>
+          <div class="nav hidden" id="nav">
+            <button id="btn-prev" title="Previous error">‹</button>
+            <span id="nav-counter"></span>
+            <button id="btn-next" title="Next error">›</button>
+          </div>
+          <button class="close-btn" id="btn-close" title="Dismiss (Escape)">✕</button>
+        </div>
+
+        <div class="card-body">
+          <pre class="message" id="err-message"></pre>
+          <div class="location hidden" id="err-location"></div>
+          <pre class="frame hidden" id="err-frame"></pre>
+          <details class="stack-details hidden" id="err-stack-wrap">
+            <summary>Stack trace</summary>
+            <pre class="stack" id="err-stack"></pre>
+          </details>
+        </div>
+
+        <div class="card-footer">
+          <span class="hint">Press <kbd>Escape</kbd> to dismiss · errors also in the browser console</span>
+        </div>
+      </div>
+    `;
+
+    // Event bindings
+    const $ = id => this._root.querySelector(`#${id}`);
+
+    $('btn-close').addEventListener('click', () => this.dismiss());
+    $('btn-prev').addEventListener('click',  () => { this._currentIndex = Math.max(0, this._currentIndex - 1); this._render(); });
+    $('btn-next').addEventListener('click',  () => { this._currentIndex = Math.min(this._errors.length - 1, this._currentIndex + 1); this._render(); });
+    this._root.querySelector('.backdrop').addEventListener('click', () => this.dismiss());
+
+    // Keyboard: Escape to dismiss, arrow keys to navigate
+    this._onKey = (e) => {
+      if (e.key === 'Escape')      this.dismiss();
+      if (e.key === 'ArrowLeft')   { this._currentIndex = Math.max(0, this._currentIndex - 1); this._render(); }
+      if (e.key === 'ArrowRight')  { this._currentIndex = Math.min(this._errors.length - 1, this._currentIndex + 1); this._render(); }
+    };
+    window.addEventListener('keydown', this._onKey);
+  }
+
+  _render() {
+    if (this._errors.length === 0) { this.dismiss(); return; }
+
+    const err = this._errors[this._currentIndex];
+    const $ = id => this._root.querySelector(`#${id}`);
+
+    // Badges
+    ['compiler', 'runtime', 'network'].forEach(t => {
+      $(`badge-${t}`).classList.toggle('hidden', err.type !== t);
+    });
+
+    // Title
+    $('err-title').textContent = err.title ?? _titleForType(err.type);
+
+    // Message
+    $('err-message').textContent = err.message;
+
+    // Location
+    const locEl = $('err-location');
+    if (err.file || err.line) {
+      locEl.classList.remove('hidden');
+      locEl.innerHTML = _buildLocation(err);
+    } else {
+      locEl.classList.add('hidden');
+    }
+
+    // Code frame
+    const frameEl = $('err-frame');
+    if (err.frame) {
+      frameEl.classList.remove('hidden');
+      frameEl.innerHTML = _highlightFrame(err.frame);
+    } else {
+      frameEl.classList.add('hidden');
+    }
+
+    // Stack
+    const stackWrap = $('err-stack-wrap');
+    if (err.stack) {
+      stackWrap.classList.remove('hidden');
+      $('err-stack').textContent = _cleanStack(err.stack);
+    } else {
+      stackWrap.classList.add('hidden');
+    }
+
+    // Nav
+    const navEl = $('nav');
+    if (this._errors.length > 1) {
+      navEl.classList.remove('hidden');
+      $('nav-counter').textContent = `${this._currentIndex + 1} / ${this._errors.length}`;
+      $('btn-prev').disabled = this._currentIndex === 0;
+      $('btn-next').disabled = this._currentIndex === this._errors.length - 1;
+    } else {
+      navEl.classList.add('hidden');
+    }
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function _normalizeError(err) {
+  if (err instanceof Error) {
+    return { type: 'runtime', message: err.message, stack: err.stack };
+  }
+  return {
+    type:    err.type    ?? 'runtime',
+    message: err.message ?? String(err),
+    file:    err.file,
+    line:    err.line,
+    col:     err.col,
+    frame:   err.frame,
+    stack:   err.stack,
+    plugin:  err.plugin,
+    title:   err.title,
+  };
+}
+
+function _titleForType(type) {
+  switch (type) {
+    case 'compiler': return 'Compiler Error';
+    case 'network':  return 'Network Error';
+    default:         return 'Runtime Error';
+  }
+}
+
+function _buildLocation({ file, line, col, plugin }) {
+  let parts = [];
+  if (file) parts.push(`<span class="loc-file">${_esc(file)}</span>`);
+  if (line) {
+    let pos = `:${line}`;
+    if (col) pos += `:${col}`;
+    parts.push(`<span class="loc-pos">${_esc(pos)}</span>`);
+  }
+  if (plugin) parts.push(`<span class="loc-plugin">via ${_esc(plugin)}</span>`);
+  return parts.join('');
+}
+
+/**
+ * Highlight the error pointer line (the one with `^`) in a code frame.
+ * Lines containing only `^` characters are wrapped in a <mark> span.
+ */
+function _highlightFrame(frame) {
+  return frame
+    .split('\n')
+    .map(line => {
+      const safe = _esc(line);
+      if (/^\s*\^+\s*$/.test(line)) return `<mark>${safe}</mark>`;
+      if (/^\s*\|\s*$/.test(line))  return `<span class="frame-pipe">${safe}</span>`;
+      return safe;
+    })
+    .join('\n');
+}
+
+/** Remove internal Clarity frames from a stack trace. */
+function _cleanStack(stack) {
+  return stack
+    .split('\n')
+    .filter(l => !l.includes('@ozsarman/clarityjs/src/devtools'))
+    .join('\n');
+}
+
+function _esc(str) {
+  return String(str ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// ─── Embedded CSS ─────────────────────────────────────────────────────────────
+
+const _CSS = `
+  :host { all: initial; font-family: monospace; }
+
+  .overlay {
+    position: fixed; inset: 0;
+    display: flex; align-items: center; justify-content: center;
+    padding: 24px;
+    box-sizing: border-box;
+  }
+
+  .backdrop {
+    position: absolute; inset: 0;
+    background: rgba(0,0,0,.65);
+    backdrop-filter: blur(2px);
+  }
+
+  .card {
+    position: relative;
+    width: 100%; max-width: 780px;
+    max-height: 90vh;
+    background: #1e1e2e;
+    border: 1px solid #f38ba8;
+    border-radius: 12px;
+    box-shadow: 0 20px 60px rgba(0,0,0,.6);
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+    color: #cdd6f4;
+    font-size: 13px;
+    line-height: 1.5;
+  }
+
+  /* ── Header ── */
+  .card-header {
+    display: flex; align-items: center; gap: 8px;
+    padding: 12px 16px;
+    background: #181825;
+    border-bottom: 1px solid #313244;
+    flex-shrink: 0;
+  }
+
+  .badge {
+    padding: 2px 8px; border-radius: 20px;
+    font-size: 10px; font-weight: 700; text-transform: uppercase;
+    letter-spacing: .05em;
+  }
+  .badge--compiler { background: #f38ba8; color: #1e1e2e; }
+  .badge--runtime  { background: #fab387; color: #1e1e2e; }
+  .badge--network  { background: #89b4fa; color: #1e1e2e; }
+  .hidden { display: none !important; }
+
+  .title { font-weight: 700; color: #f38ba8; font-size: 14px; flex: 1; }
+
+  .nav { display: flex; align-items: center; gap: 4px; color: #a6adc8; font-size: 12px; }
+  .nav button {
+    background: #313244; border: none; color: #cdd6f4;
+    width: 22px; height: 22px; border-radius: 4px; cursor: pointer;
+    font-size: 14px; display: flex; align-items: center; justify-content: center;
+  }
+  .nav button:disabled { opacity: .4; cursor: default; }
+  .nav button:hover:not(:disabled) { background: #45475a; }
+
+  .close-btn {
+    background: none; border: none; color: #6c7086;
+    cursor: pointer; font-size: 16px; padding: 2px 6px;
+    border-radius: 4px; line-height: 1;
+  }
+  .close-btn:hover { background: #313244; color: #f38ba8; }
+
+  /* ── Body ── */
+  .card-body {
+    overflow-y: auto; flex: 1; padding: 16px;
+    display: flex; flex-direction: column; gap: 12px;
+  }
+  .card-body::-webkit-scrollbar { width: 4px; }
+  .card-body::-webkit-scrollbar-thumb { background: #45475a; border-radius: 2px; }
+
+  .message {
+    margin: 0;
+    color: #f38ba8;
+    font-size: 14px; font-weight: 600;
+    white-space: pre-wrap; word-break: break-word;
+  }
+
+  .location {
+    display: flex; gap: 8px; flex-wrap: wrap;
+    font-size: 11px;
+  }
+  .loc-file   { color: #89b4fa; }
+  .loc-pos    { color: #a6e3a1; }
+  .loc-plugin { color: #cba6f7; }
+
+  .frame {
+    margin: 0;
+    padding: 12px 14px;
+    background: #181825;
+    border: 1px solid #313244;
+    border-left: 3px solid #f38ba8;
+    border-radius: 6px;
+    font-size: 12px;
+    overflow-x: auto;
+    white-space: pre;
+    color: #cdd6f4;
+    tab-size: 2;
+  }
+  .frame mark {
+    background: none; color: #f38ba8; font-weight: 700;
+  }
+  .frame .frame-pipe { color: #585b70; }
+
+  .stack-details { }
+  .stack-details summary {
+    cursor: pointer; color: #6c7086; font-size: 11px;
+    padding: 2px 0; user-select: none;
+  }
+  .stack-details summary:hover { color: #a6adc8; }
+  .stack-details[open] summary { margin-bottom: 8px; }
+
+  .stack {
+    margin: 0;
+    padding: 10px 12px;
+    background: #181825;
+    border-radius: 6px;
+    font-size: 11px;
+    color: #6c7086;
+    overflow-x: auto;
+    white-space: pre;
+  }
+
+  /* ── Footer ── */
+  .card-footer {
+    padding: 8px 16px;
+    background: #181825;
+    border-top: 1px solid #313244;
+    flex-shrink: 0;
+  }
+  .hint { color: #585b70; font-size: 10px; }
+  kbd {
+    background: #313244; border: 1px solid #45475a;
+    border-radius: 3px; padding: 1px 5px; font-family: inherit;
+    font-size: 10px;
+  }
+`;