@flight-framework/error-overlay

Unified error overlay for Flight Framework development. Displays runtime errors with source code context and stack traces.

Installation

npm install -D @flight-framework/error-overlay

Quick Start

With Vite

// vite.config.ts
import { defineConfig } from 'vite';
import { errorOverlayPlugin } from '@flight-framework/error-overlay/vite';

export default defineConfig({
    plugins: [
        errorOverlayPlugin(),
    ],
});

Manual Setup

import { createErrorOverlay } from '@flight-framework/error-overlay';

const overlay = createErrorOverlay({
    position: 'fullscreen',
    theme: 'dark',
    onOpenEditor: (file, line, column) => {
        // Open file in your editor
        fetch(`/__open-editor?file=${file}&line=${line}&column=${column}`);
    },
});

// Catch errors
window.addEventListener('error', (e) => overlay.show(e.error));
window.addEventListener('unhandledrejection', (e) => overlay.show(e.reason));

Features

• Stack trace parsing (V8, Firefox, Safari)
• Source code context with line highlighting
• Dark/light theme support
• Open in editor integration
• Keyboard shortcuts (Esc to dismiss)
• Copy error to clipboard
• User code vs vendor code distinction

Configuration

createErrorOverlay({
    // Position: 'top' | 'bottom' | 'fullscreen'
    position: 'fullscreen',

    // Theme: 'dark' | 'light' | 'auto'
    theme: 'dark',

    // Show frames from node_modules
    showNodeModules: false,

    // Lines of context around error
    contextLines: 5,

    // Enable keyboard shortcuts
    shortcuts: true,

    // Callbacks
    onDismiss: () => {},
    onOpenEditor: (file, line, column) => {},
});

API Reference

createErrorOverlay(options?)

Create an error overlay instance.

const overlay = createErrorOverlay(options);

overlay.show(error);     // Show error
overlay.hide();          // Hide overlay
overlay.destroy();       // Remove completely
overlay.isVisible();     // Check visibility
overlay.configure({});   // Update options

parseStackTrace(stack)

Parse a stack trace string into frames.

import { parseStackTrace } from '@flight-framework/error-overlay';

const frames = parseStackTrace(error.stack);
// [{ file, line, column, functionName, isUserCode, ... }]

generateSourceContext(source, line, context)

Generate source code lines around an error line.

import { generateSourceContext } from '@flight-framework/error-overlay';

const lines = generateSourceContext(sourceCode, 42, 5);
// [{ number, content, isHighlighted }]

Vite Plugin Options

errorOverlayPlugin({
    enabled: true,          // Enable/disable
    position: 'fullscreen', // Overlay position
    theme: 'dark',          // Theme
});

License

MIT