@visulima/dev-toolbar 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/rpc/functions/tailwind-config.d.ts

@@ -0,0 +1,15 @@
+import type { ViteDevServer } from "vite";
+interface TailwindConfigResult {
+    /** CSS files that \@import tailwindcss */
+    cssFiles: string[];
+    /** User-defined \@theme overrides/extensions */
+    customTheme: Record<string, string>;
+    /** Full default Tailwind theme tokens */
+    defaultTheme: Record<string, string>;
+    /** Detected Tailwind version */
+    version: "v3" | "v4" | "unknown";
+}
+declare const getTailwindConfig: (server: ViteDevServer) => Promise<TailwindConfigResult>;
+export type { TailwindConfigResult };
+export { getTailwindConfig };
+export default getTailwindConfig;

package/dist/rpc/functions/vite-config.d.ts

@@ -1,7 +1,83 @@
 import type { ViteDevServer } from "vite";
+type PluginInfo = {
+    enforce?: "post" | "pre";
+    name: string;
+};
+/** Alias entry with find always normalized to string (RegExp serialized as "/pattern/flags") */
+type AliasEntry = {
+    find: string;
+    replacement: string;
+};
+type ViteConfigSnapshot = {
+    base: string;
+    build: {
+        assetsDir?: string;
+        assetsInlineLimit?: number;
+        chunkSizeWarningLimit?: number;
+        cssCodeSplit?: boolean;
+        emptyOutDir?: boolean | null;
+        minify?: "esbuild" | "oxc" | "terser" | boolean;
+        outDir?: string;
+        reportCompressedSize?: boolean;
+        sourcemap?: "hidden" | "inline" | boolean;
+        target?: false | string | string[];
+    };
+    cacheDir: string;
+    css: {
+        devSourcemap?: boolean;
+        preprocessors: string[];
+    };
+    define?: Record<string, unknown>;
+    env?: Record<string, string>;
+    envDir?: string;
+    envPrefix?: string | string[];
+    esbuild?: {
+        jsx?: string;
+        jsxFactory?: string;
+        jsxFragment?: string;
+        jsxImportSource?: string;
+        target?: string | string[];
+    };
+    mode: string;
+    optimizeDeps: {
+        exclude?: string[];
+        include?: string[];
+    };
+    plugins: PluginInfo[];
+    publicDir: string;
+    resolve: {
+        alias?: AliasEntry[] | Record<string, string>;
+        conditions?: string[];
+        dedupe?: string[];
+        extensions?: string[];
+        mainFields?: string[];
+        preserveSymlinks?: boolean;
+    };
+    root: string;
+    server: {
+        cors?: boolean;
+        hmrEnabled?: boolean;
+        hmrPort?: number;
+        host?: boolean | string;
+        https?: boolean;
+        middlewareMode?: boolean | string;
+        open?: boolean | string;
+        origin?: string;
+        port?: number;
+        proxy?: string[];
+        strictPort?: boolean;
+    };
+    ssr?: {
+        external?: string[];
+        noExternal?: boolean | string[];
+        target?: string;
+    };
+};
 /**
- * Get Vite configuration
- * @param server Vite dev server instance
- * @returns Vite config object
+ * Gets Vite configuration from the dev server.
+ * @param server Vite dev server instance.
+ * @returns Vite config snapshot with the most useful fields.
  */
-export declare const getViteConfig: (server: ViteDevServer) => Promise<Record<string, any>>;
+declare const getViteConfig: (server: ViteDevServer) => Promise<ViteConfigSnapshot>;
+export { getViteConfig };
+export default getViteConfig;

package/dist/rpc/server.d.ts

@@ -1,9 +1,15 @@
 import type { ViteDevServer } from "vite";
 import type { ServerFunctions, ServerRPCContext } from "../types/rpc.d.ts";
 /**
- * Creates server-side RPC context
- * @param server Vite dev server instance
- * @param customFunctions Custom server functions to register
- * @returns Server RPC context
+ * Creates server-side RPC context.
+ * @param server Vite dev server instance.
+ * @param customFunctions Custom server functions to register.
+ * @param options Additional options (e.g. which editor to launch).
+ * @param options.editor Editor to use for "open in editor" functionality.
+ * @returns Server RPC context.
  */
-export declare const createServerRPCContext: (server: ViteDevServer, customFunctions?: Partial<ServerFunctions>) => ServerRPCContext;
+declare const createServerRPCContext: (server: ViteDevServer, customFunctions?: Partial<ServerFunctions>, options?: {
+    editor?: string;
+}) => ServerRPCContext;
+export { createServerRPCContext };
+export default createServerRPCContext;

package/dist/store/annotation-store.d.ts

@@ -0,0 +1,41 @@
+import type { Annotation } from "../types/annotations.d.ts";
+/** Base directory for annotation storage (relative to project root) */
+export declare const STORE_DIR = ".devtoolbar";
+export declare const ANNOTATIONS_FILE = "annotations.json";
+export declare const SCREENSHOTS_DIR = "screenshots";
+/**
+ * Resolves absolute paths for the annotation store.
+ */
+export declare const resolvePaths: (root: string) => {
+    annotationsFile: string;
+    base: string;
+    screenshotsDir: string;
+};
+/**
+ * Validates that a resolved file path stays inside the store base directory.
+ * Prevents directory traversal attacks.
+ */
+export declare const isPathInsideBase: (filepath: string, baseDir: string) => boolean;
+/**
+ * Sanitizes an ID for use as a filename — strips path separators and
+ * non-alphanumeric characters (except hyphens) to prevent traversal.
+ */
+export declare const sanitizeId: (id: string) => string;
+/**
+ * Ensures the store directories exist.
+ */
+export declare const ensureStoreDir: (root: string) => Promise<void>;
+export declare const withLock: <T>(function_: () => Promise<T>) => Promise<T>;
+/**
+ * Reads all annotations from disk.
+ */
+export declare const readAnnotations: (root: string) => Promise<Annotation[]>;
+/**
+ * Writes annotations to disk.
+ */
+export declare const writeAnnotations: (root: string, annotations: Annotation[]) => Promise<void>;
+/**
+ * Deletes a screenshot file from disk.
+ * Validates the path stays inside the store directory to prevent traversal.
+ */
+export declare const deleteScreenshotFile: (root: string, screenshotPath: string) => Promise<void>;

package/dist/timeline/capture.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Timeline event capture
+ * Intercepts HMR events, fetch requests, and JS errors and feeds them
+ * into the timeline store so the Timeline app can display them.
+ */
+declare const startTimelineCapture: () => void;
+export { startTimelineCapture };
+export default startTimelineCapture;

package/dist/timeline/index.d.ts

@@ -3,4 +3,6 @@
  */
 export type { TimelineEvent, TimelineEventLevel, TimelineGroup } from "../types/timeline.d.ts";
 export { DEFAULT_TIMELINE_GROUPS } from "../types/timeline.d.ts";
-export { getTimelineStore, TimelineStore } from "./store.d.ts";
+export { startTimelineCapture } from "./capture.d.ts";
+export type { TimelineStore } from "./store.d.ts";
+export { getTimelineStore } from "./store.d.ts";

package/dist/timeline/store.d.ts

@@ -1,52 +1,42 @@
 import type { TimelineEvent, TimelineGroup } from "../types/timeline.d.ts";
 /**
- * Timeline store for managing events
+ * Timeline store for managing timeline events.
  */
-export declare class TimelineStore {
+declare class TimelineStore {
     private groups;
     private maxEvents;
     constructor(maxEvents?: number);
     /**
-     * Add an event to a group
-     * @param groupId Group ID
-     * @param event Timeline event
+     * Adds an event to a group.
      */
     addEvent(groupId: string, event: TimelineEvent): void;
     /**
-     * Get all groups
-     * @returns Array of timeline groups
+     * Gets all timeline groups.
      */
     getGroups(): TimelineGroup[];
     /**
-     * Get events for a specific group
-     * @param groupId Group ID
-     * @returns Array of events or empty array
+     * Gets events for a specific group.
      */
     getGroupEvents(groupId: string): TimelineEvent[];
     /**
-     * Get all events across all groups
-     * @returns Array of all events
+     * Gets all events across all groups.
      */
     getAllEvents(): TimelineEvent[];
     /**
-     * Clear events for a group
-     * @param groupId Group ID
+     * Clears events for a specific group.
      */
     clearGroup(groupId: string): void;
     /**
-     * Clear all events
+     * Clears all events from all groups.
      */
     clearAll(): void;
     /**
-     * Get events within a time range
-     * @param startTime Start timestamp
-     * @param endTime End timestamp
-     * @returns Array of events in range
+     * Gets events within a time range.
      */
     getEventsInRange(startTime: number, endTime: number): TimelineEvent[];
 }
 /**
- * Get or create timeline store instance
- * @returns Timeline store instance
+ * Gets or creates the timeline store singleton instance.
  */
-export declare const getTimelineStore: () => TimelineStore;
+declare const getTimelineStore: () => TimelineStore;
+export { getTimelineStore, TimelineStore };

package/dist/toolbar/app-manager.d.ts

@@ -1,95 +1,104 @@
 import type { DevToolbarApp, DevToolbarAppState } from "../types/app.d.ts";
 /**
- * App manager for handling app lifecycle
+ * Manages the lifecycle of all registered dev-toolbar apps.
  */
-export declare class AppManager {
+declare class AppManager {
     private apps;
     private activeAppId;
     private initializedApps;
     private appCanvases;
     /**
-     * Register an app
-     * @param app App definition
-     * @param builtIn Whether this is a built-in app
+     * Registers an app with the toolbar.
+     * @param app App definition.
+     * @param builtIn Whether this is a built-in app.
      */
     registerApp(app: DevToolbarApp, builtIn?: boolean): void;
     /**
-     * Unregister an app
-     * @param appId App ID
+     * Unregisters an app and calls its destroy hook if initialized.
+     * @param appId App ID to unregister.
      */
     unregisterApp(appId: string): Promise<void>;
     /**
-     * Get an app by ID
-     * @param appId App ID
-     * @returns App state or undefined
+     * Returns the app state for a given ID.
+     * @param appId App ID to look up.
+     * @returns App state or undefined.
      */
     getApp(appId: string): DevToolbarAppState | undefined;
     /**
-     * Get all apps
-     * @returns Array of app states
+     * Returns all registered app states.
      */
     getAllApps(): DevToolbarAppState[];
     /**
-     * Get active app
-     * @returns Active app state or undefined
+     * Returns the currently active app state, or undefined if none is active.
      */
     getActiveApp(): DevToolbarAppState | undefined;
     /**
-     * Toggle app active state
-     * @param appId App ID
-     * @returns Whether toggle was successful
+     * Toggles the active state of an app.
+     * @param appId App ID to toggle.
+     * @returns Whether the toggle was successful.
      */
     toggleApp(appId: string): Promise<boolean>;
     /**
-     * Check if an app has been initialized
-     * @returns True when the app's init() has already been called
+     * Directly sets the active state of an action button without invoking callbacks.
+     * Use this to deactivate a button from outside the toolbar (e.g. after async work).
+     * @param appId The unique identifier of the app whose active state to change.
+     * @param active New active state.
+     */
+    setAppActive(appId: string, active: boolean): void;
+    /**
+     * Returns whether an app has already had its init() called.
+     * @param appId App ID to check.
      */
     isAppInitialized(appId: string): boolean;
     /**
-     * Mark an app as initialized
-     * @returns void
+     * Marks an app as having been initialized.
+     * @param appId App ID to mark.
      */
     markAppInitialized(appId: string): void;
     /**
-     * Open an app
-     * @param appId App ID
-     * @returns Whether open was successful
+     * Opens an app and initializes it if necessary.
+     * @param appId App ID to open.
+     * @returns Whether the open was successful.
      */
     openApp(appId: string): Promise<boolean>;
     /**
-     * Close an app
-     * @param appId App ID
-     * @returns Whether close was successful
+     * Closes an active app.
+     * @param appId App ID to close.
+     * @returns Whether the close was successful.
      */
     closeApp(appId: string): Promise<boolean>;
     /**
-     * Set app notification
-     * @param appId App ID
-     * @param state Notification state
-     * @param level Notification level
+     * Sets a notification for an app.
+     * @param appId The unique identifier of the app to notify.
+     * @param state Whether the notification is currently visible.
+     * @param level The severity level of the notification badge.
      */
     setNotification(appId: string, state: boolean, level?: "info" | "warning" | "error"): void;
     /**
-     * Clear app notification
-     * @param appId App ID
+     * Clears the notification for an app.
+     * @param appId The unique identifier of the app whose notification to clear.
      */
     clearNotification(appId: string): void;
     /**
-     * Get app canvas element
-     * @param appId App ID
-     * @returns Canvas element with shadow root or null
+     * Returns the canvas element and shadow root for an app.
+     * @param appId The unique identifier of the app whose canvas to retrieve.
+     * @returns Canvas element with shadow root or undefined.
      */
     getAppCanvas(appId: string): {
         element: HTMLElement;
         shadowRoot: ShadowRoot;
-    } | null;
+    } | undefined;
     /**
-     * Set app canvas element (called by toolbar component)
-     * @param appId App ID
-     * @param canvas Canvas with shadow root
+     * Stores the canvas element and shadow root for an app.
+     * @param appId The unique identifier of the app whose canvas to store.
+     * @param canvas The canvas object containing the host element and its shadow root.
+     * @param canvas.element The host HTMLElement that wraps the app's shadow DOM.
+     * @param canvas.shadowRoot The ShadowRoot attached to the canvas element.
      */
     setAppCanvas(appId: string, canvas: {
         element: HTMLElement;
         shadowRoot: ShadowRoot;
     }): void;
 }
+export { AppManager };
+export default AppManager;

package/dist/toolbar/components/app-button.d.ts

@@ -1,4 +1,3 @@
-/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 import type { DevToolbarAppState } from "../../types/index.d.ts";
 interface AppButtonProps {
@@ -11,8 +10,8 @@ interface AppButtonProps {
  * App button component — shown in the toolbar pill.
  * When an app declares a `tooltip` component, hovering the button shows a live
  * mini-canvas via AppTooltipOverlay (rendered outside overflow:hidden pill).
- * @param props - Component props
- * @param props.app - App state
+ * @param props Component props
+ * @param props.app App state
  * @returns Rendered button component
  */
 declare const AppButton: ({ app }: AppButtonProps) => ComponentChildren;

package/dist/toolbar/components/app-canvas.d.ts

@@ -1,8 +1,7 @@
-/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 import type { DevToolbarAppState } from "../../types/index.d.ts";
 interface DevPanelProps {
-    activeAppId: string | null;
+    activeAppId: string | undefined;
     apps: DevToolbarAppState[];
     onClose: () => void;
     onToggleApp: (appId: string) => Promise<void>;

package/dist/toolbar/components/app-tooltip-overlay.d.ts

@@ -1,4 +1,3 @@
-/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 interface AppTooltipOverlayProps {
     position: "bottom" | "left" | "right" | "top";

package/dist/toolbar/components/first-visit-hint.d.ts

@@ -1,4 +1,3 @@
-/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 interface FirstVisitHintProps {
     onDismiss: () => void;
@@ -7,9 +6,9 @@ interface FirstVisitHintProps {
 /**
  * First-visit hint overlay showing keyboard and interaction tips.
  * Appears ~600 ms after mount to let the toolbar pill animate in first.
- * @param props - Component props
- * @param props.onDismiss - Called after the dismiss animation completes
- * @param props.position - Current toolbar position (controls hint placement)
+ * @param props Component props
+ * @param props.onDismiss Called after the dismiss animation completes
+ * @param props.position Current toolbar position (controls hint placement)
  * @returns Rendered hint component
  */
 declare const FirstVisitHint: ({ onDismiss, position }: FirstVisitHintProps) => ComponentChildren;

package/dist/toolbar/components/pinned-tooltip-card.d.ts

@@ -1,4 +1,3 @@
-/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 import type { PinnedTooltip } from "../context/index.d.ts";
 interface PinnedTooltipCardProps {

package/dist/toolbar/components/toolbar-bar.d.ts

@@ -1,15 +1,9 @@
 /** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
-interface ToolbarBarProps {
-    /**
-     * Number of custom apps to show before "more" button
-     */
-    customAppsToShow?: number;
-}
 /**
  * Toolbar bar — row of app buttons inside the pill.
  * Left/right placement rotates the whole pill 90deg via CSS,
  * so this always stays flex-row internally.
  */
-declare const ToolbarBar: ({ customAppsToShow }: ToolbarBarProps) => ComponentChildren;
+declare const ToolbarBar: () => ComponentChildren;
 export default ToolbarBar;

package/dist/toolbar/components/toolbar-container.d.ts

@@ -1,19 +1,14 @@
-/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 import type { DevToolbarAppState } from "../../types/index.d.ts";
 interface ToolbarContainerProps {
     /**
      * Active app ID
      */
-    activeAppId: string | null;
+    activeAppId: string | undefined;
     /**
      * Initial apps
      */
     apps: DevToolbarAppState[];
-    /**
-     * Number of custom apps to show
-     */
-    customAppsToShow?: number;
     /**
      * Callback when notification should be cleared
      */
@@ -43,7 +38,6 @@ interface ToolbarContainerProps {
  * @param props Component props
  * @param props.activeAppId ID of the currently open app, or null if no app is open
  * @param props.apps Initial array of registered app states
- * @param props.customAppsToShow Maximum number of custom apps to show in the pill (default: 3)
  * @param props.onClearNotification Called when an app's notification badge should be cleared
  * @param props.onRegisterApp Called when a new app is dynamically registered
  * @param props.onSetNotification Called when an app requests a notification badge update
@@ -51,5 +45,5 @@ interface ToolbarContainerProps {
  * @param props.onUnregisterApp Called when an app is dynamically unregistered
  * @returns Rendered toolbar component tree
  */
-declare const ToolbarContainer: ({ activeAppId, apps, customAppsToShow, onClearNotification, onRegisterApp, onSetNotification, onToggleApp, onUnregisterApp, }: ToolbarContainerProps) => ComponentChildren;
+declare const ToolbarContainer: ({ activeAppId, apps, onClearNotification, onRegisterApp, onSetNotification, onToggleApp, onUnregisterApp, }: ToolbarContainerProps) => ComponentChildren;
 export default ToolbarContainer;

package/dist/toolbar/components/vite-overlay-button.d.ts

@@ -1,11 +1,10 @@
-/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 /**
- * Shows a red error button in the toolbar when @visulima/vite-overlay errors exist.
+ * Shows a red error button in the toolbar when `@visulima/vite-overlay` errors exist.
  * Clicking toggles the vite-overlay panel visibility.
  *
  * Only rendered when:
- * - @visulima/vite-overlay is installed and active (window.ErrorOverlay is defined)
+ * - `@visulima/vite-overlay` is installed and active (window.ErrorOverlay is defined)
  * - At least one error is present in the history
  *
  * Renders with its own left separator so it stays visually grouped on the

package/dist/toolbar/context/index.d.ts

@@ -1,2 +1,2 @@
-export { ToolbarContext, useToolbarContext } from "./toolbar-context.d.ts";
 export type { PinnedTooltip, ToolbarContextState } from "./toolbar-context.d.ts";
+export { ToolbarContext, useToolbarContext } from "./toolbar-context.d.ts";