@visulima/vite-overlay 2.0.0-alpha.33 → 2.0.0-alpha.34

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## @visulima/vite-overlay [2.0.0-alpha.34](https://github.com/visulima/visulima/compare/@visulima/vite-overlay@2.0.0-alpha.33...@visulima/vite-overlay@2.0.0-alpha.34) (2026-06-13)
+
+### Bug Fixes
+
+* **vite-overlay:** harden xss/redos and fix suggestion ranking in overlay ([fa7d531](https://github.com/visulima/visulima/commit/fa7d531915bde1f0fe57226f4efdc1cc1fc00ec6))
+* **vite-overlay:** restore plugin-hint fallback, Svelte hint, and XSS escaping ([15a4162](https://github.com/visulima/visulima/commit/15a41624c7f9045cebbd246821fb4a5cab28b07c))
+* **vite-overlay:** sanitize markdown, cache dir walk ([5430c78](https://github.com/visulima/visulima/commit/5430c780ab97b692d8e968900ba7b2564f19944a))
+
+### Miscellaneous Chores
+
+* **vite-overlay:** apply prettier style cleanup to src and tests ([77f376b](https://github.com/visulima/visulima/commit/77f376bd9a04032af01ba53392882d2dc95e4619))
+
+
+### Dependencies
+
+* **@visulima/error:** upgraded to 6.0.0-alpha.33
+* **@visulima/path:** upgraded to 3.0.0-alpha.13
+
 ## @visulima/vite-overlay [2.0.0-alpha.33](https://github.com/visulima/visulima/compare/@visulima/vite-overlay@2.0.0-alpha.32...@visulima/vite-overlay@2.0.0-alpha.33) (2026-06-04)
 
 ### Bug Fixes

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,8 +1,14 @@
-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";
@@ -33,6 +39,87 @@ interface OverlayConfig {
   */
   readonly customCSS?: string | Properties;
 }
+/**
+* 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.
@@ -43,22 +130,19 @@ interface OverlayConfig {
 * @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.showBallonButton Whether to show the balloon button (optional, deprecated - use overlay.balloon.enabled)
+* @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?: {
-  forwardConsole?: boolean;
-  forwardedConsoleMethods?: string[];
-  logClientRuntimeError?: boolean;
-  overlay?: OverlayConfig;
-  reactPluginName?: string;
-  showBallonButton?: boolean;
-  solutionFinders?: SolutionFinder[];
-  vuePluginName?: string;
-}) => Plugin;
+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 { errorOverlayPlugin as default };
+export { type BalloonConfig, type BalloonPosition, type BalloonStyle, type Framework, type OverlayConfig, type VisulimaViteOverlayOptions, createViteSolutionFinder, errorOverlayPlugin as default };