@visulima/dev-toolbar 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/rpc/server.d.ts

@@ -1,12 +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
- * @param options Additional options (e.g. which editor to launch)
- * @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>, options?: {
+declare const createServerRPCContext: (server: ViteDevServer, customFunctions?: Partial<ServerFunctions>, options?: {
     editor?: string;
 }) => ServerRPCContext;
+export { createServerRPCContext };
+export default createServerRPCContext;

package/dist/timeline/capture.d.ts

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

package/dist/timeline/index.d.ts

@@ -4,4 +4,5 @@
 export type { TimelineEvent, TimelineEventLevel, TimelineGroup } from "../types/timeline.d.ts";
 export { DEFAULT_TIMELINE_GROUPS } from "../types/timeline.d.ts";
 export { startTimelineCapture } from "./capture.d.ts";
-export { getTimelineStore, TimelineStore } from "./store.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,102 +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>;
     /**
-     * Directly set active state for an action button without invoking callbacks.
+     * 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 App ID
-     * @param active New active state
+     * @param appId The unique identifier of the app whose active state to change.
+     * @param active New active state.
      */
     setAppActive(appId: string, active: boolean): void;
     /**
-     * Check if an app has been initialized
-     * @returns True when the app's init() has already been called
+     * 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 {

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

@@ -1,7 +1,7 @@
 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/first-visit-hint.d.ts

@@ -1,4 +1,3 @@
-/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 interface FirstVisitHintProps {
     onDismiss: () => void;

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

@@ -1,14 +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,10 +1,10 @@
 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/toolbar-context.d.ts

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 import { createContext } from "preact";
 import type { DevToolbarAppState, ToolbarPlacement } from "../../types/index.d.ts";
 /**
@@ -14,29 +15,29 @@ export interface PinnedTooltip {
     initialY: number;
 }
 /**
- * Toolbar context state
+ * Shared state and actions exposed by the ToolbarContext.
  */
 export interface ToolbarContextState {
     /**
      * Currently active app ID
      */
-    activeAppId: string | null;
+    activeAppId: string | undefined;
     /**
      * All registered apps
      */
     apps: DevToolbarAppState[];
     /**
-     * Clear app notification
+     * Clears the notification badge for an app.
      */
     clearNotification: (appId: string) => void;
     /**
      * Currently hovered app (has a tooltip component)
      */
-    hoveredApp: DevToolbarAppState | null;
+    hoveredApp: DevToolbarAppState | undefined;
     /**
      * Viewport rect of the hovered app button (for tooltip positioning)
      */
-    hoveredAppRect: DOMRect | null;
+    hoveredAppRect: DOMRect | undefined;
     /**
      * Whether toolbar is being dragged
      */
@@ -59,48 +60,48 @@ export interface ToolbarContextState {
      */
     placement: ToolbarPlacement;
     /**
-     * Register an app
+     * Registers an app with the toolbar.
      */
     registerApp: (app: DevToolbarAppState) => void;
     /**
-     * Set dragging state
+     * Sets the dragging state.
      */
     setDragging: (dragging: boolean) => void;
     /**
-     * Set/clear the hovered app. Pass null to start the leave debounce.
+     * Sets or clears the hovered app. Pass undefined to start the leave debounce.
      */
-    setHoveredApp: (app: DevToolbarAppState | null, rect?: DOMRect | null) => void;
+    setHoveredApp: (app: DevToolbarAppState | undefined, rect?: DOMRect | undefined) => void;
     /**
-     * Set app notification
+     * Sets a notification for an app.
      */
     setNotification: (appId: string, state: boolean, level?: "info" | "warning" | "error") => void;
     /**
-     * Set toolbar placement
+     * Sets the toolbar placement.
      */
     setPlacement: (placement: ToolbarPlacement) => void;
     /**
-     * Set toolbar visibility
+     * Sets toolbar visibility.
      */
     setVisible: (visible: boolean) => void;
     /**
-     * Toggle an app
+     * Toggles an app's active state.
      */
     toggleApp: (appId: string) => Promise<void>;
     /**
-     * Remove a pinned tooltip by its instance id.
+     * Removes a pinned tooltip by its instance id.
      */
     unpinTooltip: (id: string) => void;
     /**
-     * Unregister an app
+     * Unregisters an app.
      */
     unregisterApp: (appId: string) => void;
 }
 /**
- * Toolbar context
+ * Preact context object that exposes the toolbar's shared state to all child components.
  */
-export declare const ToolbarContext: ReturnType<typeof createContext<ToolbarContextState | null>>;
+export declare const ToolbarContext: ReturnType<typeof createContext<ToolbarContextState | undefined>>;
 /**
- * Hook to access toolbar context
- * @throws Error if used outside ToolbarContext provider
+ * Accesses the toolbar context, throwing if used outside a provider.
+ * @throws Error if used outside ToolbarContext provider.
  */
 export declare const useToolbarContext: () => ToolbarContextState;

package/dist/toolbar/global-api.d.ts

@@ -1,7 +1,7 @@
 import type { VisulimaDevTools } from "../types/global-api.d.ts";
 import type { DevToolbarApp } from "../types/index.d.ts";
 /**
- * Global DevTools API implementation.
+ * Creates the global DevTools API implementation.
  */
 export declare const createGlobalAPI: (appManager: {
     clearNotification: (id: string) => void;
@@ -18,7 +18,7 @@ export declare const createGlobalAPI: (appManager: {
     toggle: () => void;
 }) => VisulimaDevTools;
 /**
- * Setup global API on window object
- * @param api API instance
+ * Mounts the global API on the window object so it can be accessed from outside the toolbar.
+ * @param api API instance to expose globally.
  */
 export declare const setupGlobalAPI: (api: VisulimaDevTools) => void;

package/dist/toolbar/helpers.d.ts

@@ -1,6 +1,8 @@
 import type { ServerHelpers } from "../types/app.d.ts";
 /**
- * Create server helpers for apps
- * @returns Server helpers instance
+ * Creates server helpers that proxy RPC calls for use within app init().
+ * @returns Server helpers instance.
  */
-export declare const createServerHelpers: () => ServerHelpers;
+declare const createServerHelpers: () => ServerHelpers;
+export { createServerHelpers };
+export default createServerHelpers;

package/dist/toolbar/hooks/use-apps.d.ts

@@ -1,9 +1,9 @@
 import type { DevToolbarAppState } from "../../types/index.d.ts";
 /**
- * Hook for app management - exposes context app methods directly
+ * Exposes app management methods from the toolbar context.
  */
-export declare const useApps: () => {
-    activeAppId: string | null;
+declare const useApps: () => {
+    activeAppId: string | undefined;
     apps: DevToolbarAppState[];
     clearNotification: (appId: string) => void;
     registerApp: (app: DevToolbarAppState) => void;
@@ -11,3 +11,5 @@ export declare const useApps: () => {
     toggleApp: (appId: string) => Promise<void>;
     unregisterApp: (appId: string) => void;
 };
+export { useApps };
+export default useApps;

package/dist/toolbar/hooks/use-frame-state.d.ts

@@ -1,21 +1,25 @@
 /**
  * Keyboard shortcut bindings
  */
-export interface KeyBindings {
+interface KeyBindings {
     /** Close active app / panel */
     close: string;
     /** Toggle toolbar panel open/closed */
     toggle: string;
 }
-export declare const DEFAULT_KEYBINDINGS: KeyBindings;
+declare const DEFAULT_KEYBINDINGS: KeyBindings;
 /**
- * Frame state interface
+ * Persistent state for the devtools panel frame.
  */
-export interface DevToolsFrameState {
+interface DevToolsFrameState {
     /**
      * Close panel on outside click
      */
     closeOnOutsideClick: boolean;
+    /**
+     * Preferred editor for "Open in editor" (empty string = auto-detect)
+     */
+    editor: string;
     /**
      * Panel height as viewport height percentage
      */
@@ -74,21 +78,33 @@ export interface DevToolsFrameState {
     width: number;
 }
 /**
- * Return type for useFrameState hook
+ * Default frame state - matches Vue DevTools exactly
+ */
+declare const DEFAULT_STATE: DevToolsFrameState;
+/**
+ * Return type for the useFrameState hook.
  */
-export interface UseFrameStateReturn {
+interface UseFrameStateReturn {
     /**
-     * Current frame state
+     * Current frame state.
      */
     state: DevToolsFrameState;
     /**
-     * Update state with partial values
+     * Updates state with partial values.
      */
     updateState: (value: Partial<DevToolsFrameState>) => void;
 }
 /**
- * Hook for frame state management.
+ * Manages the shared devtools frame state.
  * All callers share the same module-level state so position, open, and other
  * fields stay in sync regardless of how many times the hook is called.
  */
-export declare const useFrameState: () => UseFrameStateReturn;
+declare const useFrameState: () => UseFrameStateReturn;
+/**
+ * Returns the currently selected editor preference (empty string = auto-detect).
+ * Reads from the singleton shared state, so always reflects the latest value
+ * without re-reading localStorage.
+ */
+declare const getEditorPreference: () => string | undefined;
+export type { DevToolsFrameState, KeyBindings, UseFrameStateReturn };
+export { DEFAULT_KEYBINDINGS, DEFAULT_STATE, getEditorPreference, useFrameState };

package/dist/toolbar/hooks/use-panel-visible.d.ts

@@ -1,21 +1,23 @@
 /**
- * Return type for usePanelVisible hook
+ * Return type for the usePanelVisible hook.
  */
-export interface UsePanelVisibleReturn {
+interface UsePanelVisibleReturn {
     /**
-     * Close panel
+     * Closes the panel.
      */
     closePanel: () => void;
     /**
-     * Whether panel is visible
+     * Whether the panel is currently visible.
      */
     panelVisible: boolean;
     /**
-     * Toggle panel visibility
+     * Toggles panel visibility, optionally forcing a specific state.
      */
     togglePanelVisible: (_?: unknown, newState?: boolean) => void;
 }
 /**
- * Hook for panel visibility management - converted from Vue DevTools usePanelVisible
+ * Manages panel visibility with keyboard shortcut support.
  */
-export declare const usePanelVisible: () => UsePanelVisibleReturn;
+declare const usePanelVisible: () => UsePanelVisibleReturn;
+export type { UsePanelVisibleReturn };
+export { usePanelVisible };

package/dist/toolbar/hooks/use-position.d.ts

@@ -1,8 +1,8 @@
 import type { RefObject } from "preact";
 /**
- * Return type for usePosition hook
+ * Return type for usePosition hook.
  */
-export interface UsePositionReturn {
+interface UsePositionReturn {
     anchorStyle: {
         left: string;
         top: string;
@@ -12,11 +12,13 @@ export interface UsePositionReturn {
     isDragging: boolean;
     isHidden: boolean;
     isVertical: boolean;
-    onPointerDown: (e: PointerEvent) => void;
+    onPointerDown: (event: PointerEvent) => void;
     panelStyle: Record<string, string>;
 }
 /**
- * Hook for position management - converted from Vue DevTools usePosition
+ * Manages the draggable toolbar position, converted from Vue DevTools usePosition.
  * @see https://github.com/vuejs/devtools/blob/main/packages/overlay/src/composables/position.ts
  */
-export declare const usePosition: (panelElement: RefObject<HTMLElement>) => UsePositionReturn;
+declare const usePosition: (panelElement: RefObject<HTMLElement>) => UsePositionReturn;
+export type { UsePositionReturn };
+export { usePosition };

package/dist/toolbar/hooks/use-theme.d.ts

@@ -1,13 +1,15 @@
-export type Theme = "light" | "dark" | "system";
-export interface UseThemeReturn {
+type Theme = "light" | "dark" | "system";
+interface UseThemeReturn {
     resolvedTheme: "light" | "dark";
     setTheme: (newTheme: Theme) => void;
     theme: Theme;
     toggleTheme: () => void;
 }
 /**
- * Hook for managing theme (light/dark mode).
+ * Manages the shared light/dark/system theme preference.
  * All callers share the same module-level state so theme changes propagate
  * to every component (ToolbarContainer, SettingsApp, etc.) immediately.
  */
-export declare const useTheme: () => UseThemeReturn;
+declare const useTheme: () => UseThemeReturn;
+export type { Theme, UseThemeReturn };
+export { useTheme };