@visulima/dev-toolbar 1.0.0-alpha.12 → 1.0.0-alpha.14

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

@@ -1,104 +0,0 @@
-import type { DevToolbarApp, DevToolbarAppState } from "../types/app.d.ts";
-/**
- * Manages the lifecycle of all registered dev-toolbar apps.
- */
-declare class AppManager {
-    private apps;
-    private activeAppId;
-    private initializedApps;
-    private appCanvases;
-    /**
-     * 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;
-    /**
-     * Unregisters an app and calls its destroy hook if initialized.
-     * @param appId App ID to unregister.
-     */
-    unregisterApp(appId: string): Promise<void>;
-    /**
-     * 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;
-    /**
-     * Returns all registered app states.
-     */
-    getAllApps(): DevToolbarAppState[];
-    /**
-     * Returns the currently active app state, or undefined if none is active.
-     */
-    getActiveApp(): DevToolbarAppState | undefined;
-    /**
-     * 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 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;
-    /**
-     * Marks an app as having been initialized.
-     * @param appId App ID to mark.
-     */
-    markAppInitialized(appId: string): void;
-    /**
-     * 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>;
-    /**
-     * Closes an active app.
-     * @param appId App ID to close.
-     * @returns Whether the close was successful.
-     */
-    closeApp(appId: string): Promise<boolean>;
-    /**
-     * 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;
-    /**
-     * Clears the notification for an app.
-     * @param appId The unique identifier of the app whose notification to clear.
-     */
-    clearNotification(appId: string): void;
-    /**
-     * 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;
-    } | undefined;
-    /**
-     * 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,18 +0,0 @@
-import type { ComponentChildren } from "preact";
-import type { DevToolbarAppState } from "../../types/index.d.ts";
-interface AppButtonProps {
-    /**
-     * App state
-     */
-    app: DevToolbarAppState;
-}
-/**
- * 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
- * @returns Rendered button component
- */
-declare const AppButton: ({ app }: AppButtonProps) => ComponentChildren;
-export default AppButton;

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

@@ -1,12 +0,0 @@
-import type { ComponentChildren } from "preact";
-import type { DevToolbarAppState } from "../../types/index.d.ts";
-interface DevPanelProps {
-    activeAppId: string | undefined;
-    apps: DevToolbarAppState[];
-    onClose: () => void;
-    onToggleApp: (appId: string) => Promise<void>;
-    panelVisible: boolean;
-    position: "bottom" | "left" | "right" | "top";
-}
-declare const DevPanel: ({ activeAppId, apps, onClose, onToggleApp, panelVisible, position }: DevPanelProps) => ComponentChildren;
-export default DevPanel;

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

@@ -1,12 +0,0 @@
-import type { ComponentChildren } from "preact";
-interface AppTooltipOverlayProps {
-    position: "bottom" | "left" | "right" | "top";
-}
-/**
- * Floating mini-canvas that appears when hovering a toolbar app button that
- * provides a `tooltip` component. Rendered as `position:fixed` so it escapes
- * the pill's `overflow:hidden`. The leave-debounce (handled in ToolbarContainer)
- * keeps it visible while the mouse moves from button to tooltip.
- */
-declare const AppTooltipOverlay: ({ position }: AppTooltipOverlayProps) => ComponentChildren;
-export default AppTooltipOverlay;

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

@@ -1,15 +0,0 @@
-import type { ComponentChildren } from "preact";
-interface FirstVisitHintProps {
-    onDismiss: () => void;
-    position: "bottom" | "left" | "right" | "top";
-}
-/**
- * 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)
- * @returns Rendered hint component
- */
-declare const FirstVisitHint: ({ onDismiss, position }: FirstVisitHintProps) => ComponentChildren;
-export default FirstVisitHint;

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

@@ -1,4 +0,0 @@
-export { default as AppButton } from "./app-button.d.ts";
-export { default as AppCanvas } from "./app-canvas.d.ts";
-export { default as ToolbarBar } from "./toolbar-bar.d.ts";
-export { default as ToolbarContainer } from "./toolbar-container.d.ts";

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

@@ -1,22 +0,0 @@
-import type { ComponentChildren } from "preact";
-import type { PinnedTooltip } from "../context/index.d.ts";
-interface PinnedTooltipCardProps {
-    /** Called once when a drag ends so the parent can persist the new position. */
-    onMove: (id: string, x: number, y: number) => void;
-    onUnpin: (id: string) => void;
-    pinned: PinnedTooltip;
-}
-/**
- * A pinned tooltip card — persists on screen until the user unpins it.
- *
- * Position is updated via direct DOM style mutations during drag so that
- * Preact never re-renders the component on mousemove — drag is silky smooth
- * regardless of how expensive the tooltip content component is.
- * @param props Component props
- * @param props.onMove Called with the pin ID and final (x, y) coordinates when a drag ends
- * @param props.onUnpin Called with the pin ID when the user clicks the unpin button
- * @param props.pinned Pinned tooltip descriptor — contains the app reference and initial position
- * @returns Rendered draggable pinned card, or null if the app has no tooltip component
- */
-declare const PinnedTooltipCard: ({ onMove, onUnpin, pinned }: PinnedTooltipCardProps) => ComponentChildren;
-export default PinnedTooltipCard;

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

@@ -1,9 +0,0 @@
-/** @jsxImportSource preact */
-import type { ComponentChildren } from "preact";
-/**
- * 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: () => ComponentChildren;
-export default ToolbarBar;

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

@@ -1,49 +0,0 @@
-import type { ComponentChildren } from "preact";
-import type { DevToolbarAppState } from "../../types/index.d.ts";
-interface ToolbarContainerProps {
-    /**
-     * Active app ID
-     */
-    activeAppId: string | undefined;
-    /**
-     * Initial apps
-     */
-    apps: DevToolbarAppState[];
-    /**
-     * Callback when notification should be cleared
-     */
-    onClearNotification: (appId: string) => void;
-    /**
-     * Callback when app should be registered
-     */
-    onRegisterApp: (app: DevToolbarAppState) => void;
-    /**
-     * Callback when notification should be set
-     */
-    onSetNotification: (appId: string, state: boolean, level?: "error" | "info" | "warning") => void;
-    /**
-     * Callback when app should be toggled
-     */
-    onToggleApp: (appId: string) => Promise<void>;
-    /**
-     * Callback when app should be unregistered
-     */
-    onUnregisterApp: (appId: string) => void;
-}
-/**
- * Root toolbar container component — orchestrates the toolbar pill, app panel,
- * tooltip overlays, pinned cards, and first-visit hint.
- * Manages active app state, hover tooltips, pinned tooltip persistence (localStorage),
- * and delegates app lifecycle events to the parent via callbacks.
- * @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.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
- * @param props.onToggleApp Called when the user clicks an app button to open/close it
- * @param props.onUnregisterApp Called when an app is dynamically unregistered
- * @returns Rendered toolbar component tree
- */
-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,14 +0,0 @@
-import type { ComponentChildren } from "preact";
-/**
- * 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)
- * - At least one error is present in the history
- *
- * Renders with its own left separator so it stays visually grouped on the
- * right side of the toolbar, distinct from the regular app buttons.
- */
-declare const ViteOverlayButton: () => ComponentChildren;
-export default ViteOverlayButton;

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

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

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

@@ -1,107 +0,0 @@
-/** @jsxImportSource preact */
-import { createContext } from "preact";
-import type { DevToolbarAppState, ToolbarPlacement } from "../../types/index.d.ts";
-/**
- * A tooltip that has been pinned by the user — stays visible until unpinned.
- */
-export interface PinnedTooltip {
-    /** The app whose tooltip is shown */
-    app: DevToolbarAppState;
-    /** Unique instance identifier (appId + timestamp) */
-    id: string;
-    /** Initial left position (viewport px) */
-    initialX: number;
-    /** Initial top position (viewport px) */
-    initialY: number;
-}
-/**
- * Shared state and actions exposed by the ToolbarContext.
- */
-export interface ToolbarContextState {
-    /**
-     * Currently active app ID
-     */
-    activeAppId: string | undefined;
-    /**
-     * All registered apps
-     */
-    apps: DevToolbarAppState[];
-    /**
-     * Clears the notification badge for an app.
-     */
-    clearNotification: (appId: string) => void;
-    /**
-     * Currently hovered app (has a tooltip component)
-     */
-    hoveredApp: DevToolbarAppState | undefined;
-    /**
-     * Viewport rect of the hovered app button (for tooltip positioning)
-     */
-    hoveredAppRect: DOMRect | undefined;
-    /**
-     * Whether toolbar is being dragged
-     */
-    isDragging: boolean;
-    /**
-     * Whether toolbar is visible
-     */
-    isVisible: boolean;
-    /**
-     * Currently pinned tooltip cards
-     */
-    pinnedTooltips: PinnedTooltip[];
-    /**
-     * Pin a tooltip at the given viewport position.
-     * Multiple pins from the same app are allowed (each gets a unique id).
-     */
-    pinTooltip: (app: DevToolbarAppState, x: number, y: number) => void;
-    /**
-     * Toolbar placement on screen
-     */
-    placement: ToolbarPlacement;
-    /**
-     * Registers an app with the toolbar.
-     */
-    registerApp: (app: DevToolbarAppState) => void;
-    /**
-     * Sets the dragging state.
-     */
-    setDragging: (dragging: boolean) => void;
-    /**
-     * Sets or clears the hovered app. Pass undefined to start the leave debounce.
-     */
-    setHoveredApp: (app: DevToolbarAppState | undefined, rect?: DOMRect) => void;
-    /**
-     * Sets a notification for an app.
-     */
-    setNotification: (appId: string, state: boolean, level?: "info" | "warning" | "error") => void;
-    /**
-     * Sets the toolbar placement.
-     */
-    setPlacement: (placement: ToolbarPlacement) => void;
-    /**
-     * Sets toolbar visibility.
-     */
-    setVisible: (visible: boolean) => void;
-    /**
-     * Toggles an app's active state.
-     */
-    toggleApp: (appId: string) => Promise<void>;
-    /**
-     * Removes a pinned tooltip by its instance id.
-     */
-    unpinTooltip: (id: string) => void;
-    /**
-     * Unregisters an app.
-     */
-    unregisterApp: (appId: string) => void;
-}
-/**
- * Preact context object that exposes the toolbar's shared state to all child components.
- */
-export declare const ToolbarContext: ReturnType<typeof createContext<ToolbarContextState | undefined>>;
-/**
- * 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,24 +0,0 @@
-import type { VisulimaDevTools } from "../types/global-api.d.ts";
-import type { DevToolbarApp } from "../types/index.d.ts";
-/**
- * Creates the global DevTools API implementation.
- */
-export declare const createGlobalAPI: (appManager: {
-    clearNotification: (id: string) => void;
-    getActiveApp: () => DevToolbarApp | undefined;
-    getApps: () => DevToolbarApp[];
-    registerApp: (app: DevToolbarApp) => void;
-    setAppActive: (id: string, active: boolean) => void;
-    setNotification: (id: string, state: boolean, level?: "info" | "warning" | "error") => void;
-    toggleApp: (id: string) => Promise<boolean>;
-    unregisterApp: (id: string) => void;
-}, toolbar: {
-    hide: () => void;
-    show: () => void;
-    toggle: () => void;
-}) => VisulimaDevTools;
-/**
- * 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,8 +0,0 @@
-import type { ServerHelpers } from "../types/app.d.ts";
-/**
- * Creates server helpers that proxy RPC calls for use within app init().
- * @returns Server helpers instance.
- */
-declare const createServerHelpers: () => ServerHelpers;
-export { createServerHelpers };
-export default createServerHelpers;

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

@@ -1,10 +0,0 @@
-export { useApps } from "./use-apps.d.ts";
-export type { DevToolsFrameState, UseFrameStateReturn } from "./use-frame-state.d.ts";
-export { useFrameState } from "./use-frame-state.d.ts";
-export type { UsePanelVisibleReturn } from "./use-panel-visible.d.ts";
-export { usePanelVisible } from "./use-panel-visible.d.ts";
-export type { UsePositionReturn } from "./use-position.d.ts";
-export { usePosition } from "./use-position.d.ts";
-export type { Theme, UseThemeReturn } from "./use-theme.d.ts";
-export { useTheme } from "./use-theme.d.ts";
-export { useToolbar } from "./use-toolbar.d.ts";

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

@@ -1,15 +0,0 @@
-import type { DevToolbarAppState } from "../../types/index.d.ts";
-/**
- * Exposes app management methods from the toolbar context.
- */
-declare const useApps: () => {
-    activeAppId: string | undefined;
-    apps: DevToolbarAppState[];
-    clearNotification: (appId: string) => void;
-    registerApp: (app: DevToolbarAppState) => void;
-    setNotification: (appId: string, state: boolean, level?: "info" | "warning" | "error") => void;
-    toggleApp: (appId: string) => Promise<void>;
-    unregisterApp: (appId: string) => void;
-};
-export { useApps };
-export default useApps;

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

@@ -1,110 +0,0 @@
-/**
- * Keyboard shortcut bindings
- */
-interface KeyBindings {
-    /** Close active app / panel */
-    close: string;
-    /** Toggle toolbar panel open/closed */
-    toggle: string;
-}
-declare const DEFAULT_KEYBINDINGS: KeyBindings;
-/**
- * Persistent state for the devtools panel frame.
- */
-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
-     */
-    height: number;
-    /**
-     * Whether this is the first visit (used to show onboarding hint)
-     */
-    isFirstVisit: boolean;
-    /**
-     * Whether DevTools panel is open in a Picture-in-Picture window
-     */
-    isPip: boolean;
-    /**
-     * Keyboard shortcut bindings
-     */
-    keybindings: KeyBindings;
-    /**
-     * Horizontal position as percentage (0-100)
-     */
-    left: number;
-    /**
-     * Auto-hide timeout in milliseconds (-1 = never hide, 0 = always hide when inactive)
-     */
-    minimizePanelInactive: number;
-    /**
-     * Whether panel is open
-     */
-    open: boolean;
-    /**
-     * Position anchor
-     */
-    position: "top" | "bottom" | "left" | "right";
-    /**
-     * Prefer showing floating panel
-     */
-    preferShowFloatingPanel: boolean;
-    /**
-     * Reduce motion for accessibility
-     */
-    reduceMotion: boolean;
-    /**
-     * Current route
-     */
-    route: string;
-    /**
-     * Vertical position as percentage (0-100)
-     */
-    top: number;
-    /**
-     * Panel view mode
-     */
-    viewMode: "default" | "fullscreen" | "wide";
-    /**
-     * Panel width as viewport width percentage
-     */
-    width: number;
-}
-/**
- * Default frame state - matches Vue DevTools exactly
- */
-declare const DEFAULT_STATE: DevToolsFrameState;
-/**
- * Return type for the useFrameState hook.
- */
-interface UseFrameStateReturn {
-    /**
-     * Current frame state.
-     */
-    state: DevToolsFrameState;
-    /**
-     * Updates state with partial values.
-     */
-    updateState: (value: Partial<DevToolsFrameState>) => void;
-}
-/**
- * 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.
- */
-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,23 +0,0 @@
-/**
- * Return type for the usePanelVisible hook.
- */
-interface UsePanelVisibleReturn {
-    /**
-     * Closes the panel.
-     */
-    closePanel: () => void;
-    /**
-     * Whether the panel is currently visible.
-     */
-    panelVisible: boolean;
-    /**
-     * Toggles panel visibility, optionally forcing a specific state.
-     */
-    togglePanelVisible: (_?: unknown, newState?: boolean) => void;
-}
-/**
- * Manages panel visibility with keyboard shortcut support.
- */
-declare const usePanelVisible: () => UsePanelVisibleReturn;
-export type { UsePanelVisibleReturn };
-export { usePanelVisible };

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

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

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

@@ -1,15 +0,0 @@
-type Theme = "light" | "dark" | "system";
-interface UseThemeReturn {
-    resolvedTheme: "light" | "dark";
-    setTheme: (newTheme: Theme) => void;
-    theme: Theme;
-    toggleTheme: () => void;
-}
-/**
- * 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.
- */
-declare const useTheme: () => UseThemeReturn;
-export type { Theme, UseThemeReturn };
-export { useTheme };

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

@@ -1,16 +0,0 @@
-import type { ToolbarPlacement } from "../../types/index.d.ts";
-/**
- * Exposes toolbar visibility and placement controls from the toolbar context.
- */
-declare const useToolbar: () => {
-    hide: () => void;
-    isDragging: boolean;
-    isVisible: boolean;
-    placement: ToolbarPlacement;
-    setDragging: (dragging: boolean) => void;
-    setPlacement: (placement: ToolbarPlacement) => void;
-    show: () => void;
-    toggle: () => void;
-};
-export { useToolbar };
-export default useToolbar;

package/dist/toolbar/settings.d.ts

@@ -1,17 +0,0 @@
-import type { ToolbarSettings } from "../types/toolbar.d.ts";
-/**
- * Loads settings from localStorage, merging with defaults.
- * @returns Toolbar settings.
- */
-export declare const loadSettings: () => ToolbarSettings;
-/**
- * Saves settings to localStorage.
- * @param settings Toolbar settings to save.
- */
-export declare const saveSettings: (settings: ToolbarSettings) => void;
-/**
- * Merges partial updates into the current settings and persists them.
- * @param updates Partial settings to update.
- * @returns Updated settings.
- */
-export declare const updateSettings: (updates: Partial<ToolbarSettings>) => ToolbarSettings;

package/dist/toolbar/stylesheet.d.ts

@@ -1,3 +0,0 @@
-declare const sharedToolbarStylesheet: CSSStyleSheet | undefined;
-export { sharedToolbarStylesheet };
-export default sharedToolbarStylesheet;