@visulima/vite-overlay 2.0.0-alpha.9 → 2.0.1

package/README.md

@@ -93,14 +93,23 @@ export default defineConfig({
             // Array of console method names to forward (default: ["error"])
             forwardedConsoleMethods: ["error", "warn"],
 
-            // Custom React plugin name for detection (optional)
+            // Custom plugin names for framework detection (all optional)
             reactPluginName: "@vitejs/plugin-react",
-
-            // Custom Vue plugin name for detection (optional)
             vuePluginName: "@vitejs/plugin-vue",
+            sveltePluginName: "@sveltejs/vite-plugin-svelte",
+            preactPluginName: "@preact/preset-vite",
+            solidPluginName: "vite-plugin-solid",
+
+            // Explicit framework override; skips auto-detection (optional)
+            // "react" | "vue" | "svelte" | "preact" | "solid"
+            framework: "react",
+
+            // Capture process-wide unhandled rejections and show them in the overlay (default: true).
+            // Set to false to leave Node's default crash semantics untouched.
+            interceptUnhandledRejection: true,
 
             // Whether to show the balloon button in the overlay (default: true)
-            showBallonButton: true,
+            showBalloonButton: true,
 
             // Overlay configuration (optional)
             overlay: {
@@ -138,19 +147,25 @@ export default defineConfig({
 
 #### Options
 
-| Option                    | Type                       | Default     | Description                                                                      |
-| ------------------------- | -------------------------- | ----------- | -------------------------------------------------------------------------------- |
-| `forwardConsole`          | `boolean`                  | `true`      | Enable/disable client-side runtime error logging and overlay display             |
-| `forwardedConsoleMethods` | `string[]`                 | `["error"]` | Array of console method names to intercept and forward to overlay                |
-| `reactPluginName`         | `string`                   | `undefined` | Custom React plugin name for detection (useful for custom React plugins)         |
-| `vuePluginName`           | `string`                   | `undefined` | Custom Vue plugin name for detection (useful for custom Vue plugins)             |
-| `showBallonButton`        | `boolean`                  | `true`      | Whether to show the floating balloon button for error navigation                 |
-| `overlay`                 | `OverlayConfig`            | `undefined` | Overlay configuration options                                                    |
-| `overlay.balloon`         | `BalloonConfig`            | `undefined` | Balloon button configuration                                                     |
-| `overlay.balloon.style`   | `string \| CSS.Properties` | `undefined` | Balloon button styles (string or CSS.Properties object)                          |
-| `overlay.customCSS`       | `string \| CSS.Properties` | `undefined` | Custom CSS to inject for styling customization (string or CSS.Properties object) |
-| `solutionFinders`         | `SolutionFinder[]`         | `[]`        | Array of custom solution finder functions for enhanced error analysis            |
-| `logClientRuntimeError`   | `boolean`                  | `undefined` | **@deprecated** Use `forwardConsole` instead                                     |
+| Option                        | Type                                                  | Default     | Description                                                                      |
+| ----------------------------- | ----------------------------------------------------- | ----------- | -------------------------------------------------------------------------------- |
+| `forwardConsole`              | `boolean`                                             | `true`      | Enable/disable client-side runtime error logging and overlay display             |
+| `forwardedConsoleMethods`     | `string[]`                                            | `["error"]` | Array of console method names to intercept and forward to overlay                |
+| `framework`                   | `"react" \| "vue" \| "svelte" \| "preact" \| "solid"` | `undefined` | Explicit framework override; skips auto-detection                                |
+| `interceptUnhandledRejection` | `boolean`                                             | `true`      | Capture process-wide `unhandledRejection` and render it in the overlay           |
+| `reactPluginName`             | `string`                                              | `undefined` | Custom React plugin name for detection                                           |
+| `vuePluginName`               | `string`                                              | `undefined` | Custom Vue plugin name for detection                                             |
+| `sveltePluginName`            | `string`                                              | `undefined` | Custom Svelte plugin name for detection                                          |
+| `preactPluginName`            | `string`                                              | `undefined` | Custom Preact plugin name for detection                                          |
+| `solidPluginName`             | `string`                                              | `undefined` | Custom Solid plugin name for detection                                           |
+| `showBalloonButton`           | `boolean`                                             | `true`      | Whether to show the floating balloon button for error navigation                 |
+| `overlay`                     | `OverlayConfig`                                       | `undefined` | Overlay configuration options                                                    |
+| `overlay.balloon`             | `BalloonConfig`                                       | `undefined` | Balloon button configuration                                                     |
+| `overlay.balloon.style`       | `string \| CSS.Properties`                            | `undefined` | Balloon button styles (string or CSS.Properties object)                          |
+| `overlay.customCSS`           | `string \| CSS.Properties`                            | `undefined` | Custom CSS to inject for styling customization (string or CSS.Properties object) |
+| `solutionFinders`             | `SolutionFinder[]`                                    | `[]`        | Array of custom solution finder functions for enhanced error analysis            |
+| `showBallonButton`            | `boolean`                                             | `undefined` | **@deprecated** Misspelling of `showBalloonButton`                               |
+| `logClientRuntimeError`       | `boolean`                                             | `undefined` | **@deprecated** Use `forwardConsole` instead                                     |
 
 ## Error Handling
 
@@ -188,7 +203,7 @@ When errors occur, a floating balloon button appears in the bottom-right corner
 - Navigate through multiple errors
 - Access error overlay controls
 
-The balloon button can be disabled by setting `showBallonButton: false` in the plugin options.
+The balloon button can be disabled by setting `showBalloonButton: false` in the plugin options.
 
 ### Keyboard Shortcuts
 
@@ -202,10 +217,16 @@ The balloon button can be disabled by setting `showBallonButton: false` in the p
 
 You can extend the plugin with custom solution finders:
 
+All public option types are exported from the package, so you can type a shared config object or a custom solution finder without reaching into `@visulima/error`:
+
+```typescript
+import type { BalloonConfig, BalloonPosition, OverlayConfig, SolutionFinder, VisulimaViteOverlayOptions } from "@visulima/vite-overlay";
+```
+
 ```typescript
 import { defineConfig } from "vite";
 import errorOverlay from "@visulima/vite-overlay";
-import type { SolutionFinder } from "@visulima/error/solution";
+import type { SolutionFinder } from "@visulima/vite-overlay";
 
 const customSolutionFinder: SolutionFinder = {
     name: "custom-finder",

package/dist/index.d.ts

@@ -1,27 +1,148 @@
-import { SolutionFinder } from '@visulima/error/solution';
 import { Plugin } from 'vite';
 import '@visulima/error/error';
+import { SolutionFinder } from '@visulima/error/solution';
+export type { Solution, SolutionFinder } from '@visulima/error/solution';
 import { Properties } from 'csstype';
+/**
+* Framework hint used to route framework-aware solutions. When omitted, the plugin
+* auto-detects the framework from the configured Vite plugins.
+*/
+type Framework = "preact" | "react" | "solid" | "svelte" | "vue";
+/**
+* Balloon position options
+*/
 type BalloonPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/**
+* Custom style options for the balloon trigger
+* Can be either a CSS string or a CSS.Properties object
+*/
 type BalloonStyle = string | Properties;
+/**
+* Balloon configuration options
+*/
 interface BalloonConfig {
   readonly enabled?: boolean;
   readonly icon?: string;
   readonly position?: BalloonPosition;
   readonly style?: BalloonStyle;
 }
+/**
+* Overlay configuration options
+*/
 interface OverlayConfig {
   readonly balloon?: BalloonConfig;
+  /**
+  * Custom CSS to inject into the overlay for styling customization.
+  * This CSS will be injected into the shadow DOM and can be used to override
+  * the default styles of the overlay and button elements.
+  * Can be either a CSS string or a CSS.Properties object.
+  */
   readonly customCSS?: string | Properties;
 }
-declare const errorOverlayPlugin: (options?: {
-  forwardConsole?: boolean;
-  forwardedConsoleMethods?: string[];
-  logClientRuntimeError?: boolean;
-  overlay?: OverlayConfig;
-  reactPluginName?: string;
-  showBallonButton?: boolean;
-  solutionFinders?: SolutionFinder[];
-  vuePluginName?: string;
-}) => Plugin;
-export { errorOverlayPlugin as default };
+/**
+* Options accepted by the `@visulima/vite-overlay` plugin.
+*/
+interface VisulimaViteOverlayOptions {
+  /**
+  * Whether client runtime errors are forwarded to (and displayed in) the overlay.
+  * @default true
+  */
+  readonly forwardConsole?: boolean;
+  /**
+  * Console method names to forward from the client (e.g. `["error", "warn"]`).
+  * @default ["error"]
+  */
+  readonly forwardedConsoleMethods?: string[];
+  /**
+  * Explicitly set the framework used for framework-aware hints. When omitted, the plugin
+  * auto-detects React / Vue / Svelte / Preact / Solid from the configured Vite plugins.
+  */
+  readonly framework?: Framework;
+  /**
+  * Capture process-wide `unhandledRejection` events and render them in the overlay.
+  * Set to `false` to leave Node's default crash semantics untouched (useful when other
+  * tooling in the dev process produces unrelated rejections).
+  * @default true
+  */
+  readonly interceptUnhandledRejection?: boolean;
+  /**
+  * @deprecated Use {@link VisulimaViteOverlayOptions.forwardConsole} instead.
+  */
+  readonly logClientRuntimeError?: boolean;
+  /**
+  * Overlay UI configuration (balloon button, custom CSS).
+  */
+  readonly overlay?: OverlayConfig;
+  /**
+  * Custom Preact plugin name to match during auto-detection.
+  */
+  readonly preactPluginName?: string;
+  /**
+  * Custom React plugin name to match during auto-detection.
+  */
+  readonly reactPluginName?: string;
+  /**
+  * @deprecated Misspelling of {@link VisulimaViteOverlayOptions.showBalloonButton}. Kept for
+  * backward compatibility; prefer `showBalloonButton` or `overlay.balloon.enabled`.
+  */
+  readonly showBallonButton?: boolean;
+  /**
+  * Whether to show the balloon button.
+  * @default true
+  */
+  readonly showBalloonButton?: boolean;
+  /**
+  * Custom Solid plugin name to match during auto-detection.
+  */
+  readonly solidPluginName?: string;
+  /**
+  * Custom solution finders to run before the built-in finders.
+  */
+  readonly solutionFinders?: SolutionFinder[];
+  /**
+  * Custom Svelte plugin name to match during auto-detection.
+  */
+  readonly sveltePluginName?: string;
+  /**
+  * Custom Vue plugin name to match during auto-detection.
+  */
+  readonly vuePluginName?: string;
+}
+/**
+* Creates a solution finder specifically designed for Vite-related errors.
+* Provides intelligent suggestions for common Vite import resolution and configuration issues.
+* @param rootPath The root path of the project
+* @returns A solution finder object for Vite-specific error handling
+*/
+declare const createViteSolutionFinder: (rootPath: string) => SolutionFinder;
+/**
+* Default export for creating Vite solution finders.
+* @see createViteSolutionFinder
+*/
+
+/**
+* Main Vite plugin for error overlay functionality.
+* Intercepts runtime errors and displays them in a user-friendly overlay.
+* @param options Plugin configuration options
+* @param options.forwardConsole Whether to log client runtime errors (optional)
+* @param options.forwardedConsoleMethods Array of console method names to forward (optional)
+* @param [options.logClientRuntimeError] [deprecated] Use forwardConsole instead
+* @param options.reactPluginName Custom React plugin name (optional)
+* @param options.solutionFinders Custom solution finders (optional)
+* @param options.vuePluginName Custom Vue plugin name (optional)
+* @param options.sveltePluginName Custom Svelte plugin name (optional)
+* @param options.preactPluginName Custom Preact plugin name (optional)
+* @param options.solidPluginName Custom Solid plugin name (optional)
+* @param options.framework Explicit framework override; skips auto-detection (optional)
+* @param options.interceptUnhandledRejection Capture process-wide unhandled rejections (optional, default true)
+* @param options.showBalloonButton Whether to show the balloon button (optional)
+* @param options.showBallonButton [deprecated] Misspelling of showBalloonButton
+* @param options.overlay Overlay configuration (optional)
+* @returns The Vite plugin configuration
+*/
+declare const errorOverlayPlugin: (options?: VisulimaViteOverlayOptions) => Plugin;
+/**
+* Default export of the Vite error overlay plugin.
+* Use this plugin to enable error overlay functionality in your Vite project.
+*/
+export { type BalloonConfig, type BalloonPosition, type BalloonStyle, type Framework, type OverlayConfig, type VisulimaViteOverlayOptions, createViteSolutionFinder, errorOverlayPlugin as default };