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

package/dist/timeline/store.d.ts

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

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

@@ -0,0 +1,95 @@
+import type { DevToolbarApp, DevToolbarAppState } from "../types/app.d.ts";
+/**
+ * App manager for handling app lifecycle
+ */
+export 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
+     */
+    registerApp(app: DevToolbarApp, builtIn?: boolean): void;
+    /**
+     * Unregister an app
+     * @param appId App ID
+     */
+    unregisterApp(appId: string): Promise<void>;
+    /**
+     * Get an app by ID
+     * @param appId App ID
+     * @returns App state or undefined
+     */
+    getApp(appId: string): DevToolbarAppState | undefined;
+    /**
+     * Get all apps
+     * @returns Array of app states
+     */
+    getAllApps(): DevToolbarAppState[];
+    /**
+     * Get active app
+     * @returns Active app state or undefined
+     */
+    getActiveApp(): DevToolbarAppState | undefined;
+    /**
+     * Toggle app active state
+     * @param appId App ID
+     * @returns Whether 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
+     */
+    isAppInitialized(appId: string): boolean;
+    /**
+     * Mark an app as initialized
+     * @returns void
+     */
+    markAppInitialized(appId: string): void;
+    /**
+     * Open an app
+     * @param appId App ID
+     * @returns Whether open was successful
+     */
+    openApp(appId: string): Promise<boolean>;
+    /**
+     * Close an app
+     * @param appId App ID
+     * @returns Whether close was successful
+     */
+    closeApp(appId: string): Promise<boolean>;
+    /**
+     * Set app notification
+     * @param appId App ID
+     * @param state Notification state
+     * @param level Notification level
+     */
+    setNotification(appId: string, state: boolean, level?: "info" | "warning" | "error"): void;
+    /**
+     * Clear app notification
+     * @param appId App ID
+     */
+    clearNotification(appId: string): void;
+    /**
+     * Get app canvas element
+     * @param appId App ID
+     * @returns Canvas element with shadow root or null
+     */
+    getAppCanvas(appId: string): {
+        element: HTMLElement;
+        shadowRoot: ShadowRoot;
+    } | null;
+    /**
+     * Set app canvas element (called by toolbar component)
+     * @param appId App ID
+     * @param canvas Canvas with shadow root
+     */
+    setAppCanvas(appId: string, canvas: {
+        element: HTMLElement;
+        shadowRoot: ShadowRoot;
+    }): void;
+}

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

@@ -0,0 +1,19 @@
+/** @jsxImportSource preact */
+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

@@ -0,0 +1,13 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren } from "preact";
+import type { DevToolbarAppState } from "../../types/index.d.ts";
+interface DevPanelProps {
+    activeAppId: string | null;
+    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

@@ -0,0 +1,13 @@
+/** @jsxImportSource preact */
+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

@@ -0,0 +1,16 @@
+/** @jsxImportSource preact */
+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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,23 @@
+/** @jsxImportSource preact */
+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

@@ -0,0 +1,15 @@
+/** @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;
+export default ToolbarBar;

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

@@ -0,0 +1,55 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren } from "preact";
+import type { DevToolbarAppState } from "../../types/index.d.ts";
+interface ToolbarContainerProps {
+    /**
+     * Active app ID
+     */
+    activeAppId: string | null;
+    /**
+     * Initial apps
+     */
+    apps: DevToolbarAppState[];
+    /**
+     * Number of custom apps to show
+     */
+    customAppsToShow?: number;
+    /**
+     * 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.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
+ * @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, customAppsToShow, onClearNotification, onRegisterApp, onSetNotification, onToggleApp, onUnregisterApp, }: ToolbarContainerProps) => ComponentChildren;
+export default ToolbarContainer;

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

@@ -0,0 +1,15 @@
+/** @jsxImportSource preact */
+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

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

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

@@ -0,0 +1,106 @@
+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;
+}
+/**
+ * Toolbar context state
+ */
+export interface ToolbarContextState {
+    /**
+     * All registered apps
+     */
+    apps: DevToolbarAppState[];
+    /**
+     * Currently active app ID
+     */
+    activeAppId: string | null;
+    /**
+     * Whether toolbar is visible
+     */
+    isVisible: boolean;
+    /**
+     * Toolbar placement on screen
+     */
+    placement: ToolbarPlacement;
+    /**
+     * Whether toolbar is being dragged
+     */
+    isDragging: boolean;
+    /**
+     * Set toolbar visibility
+     */
+    setVisible: (visible: boolean) => void;
+    /**
+     * Set toolbar placement
+     */
+    setPlacement: (placement: ToolbarPlacement) => void;
+    /**
+     * Set dragging state
+     */
+    setDragging: (dragging: boolean) => void;
+    /**
+     * Register an app
+     */
+    registerApp: (app: DevToolbarAppState) => void;
+    /**
+     * Unregister an app
+     */
+    unregisterApp: (appId: string) => void;
+    /**
+     * Toggle an app
+     */
+    toggleApp: (appId: string) => Promise<void>;
+    /**
+     * Set app notification
+     */
+    setNotification: (appId: string, state: boolean, level?: "info" | "warning" | "error") => void;
+    /**
+     * Clear app notification
+     */
+    clearNotification: (appId: string) => void;
+    /**
+     * Currently hovered app (has a tooltip component)
+     */
+    hoveredApp: DevToolbarAppState | null;
+    /**
+     * Viewport rect of the hovered app button (for tooltip positioning)
+     */
+    hoveredAppRect: DOMRect | null;
+    /**
+     * Set/clear the hovered app. Pass null to start the leave debounce.
+     */
+    setHoveredApp: (app: DevToolbarAppState | null, rect?: DOMRect | null) => void;
+    /**
+     * 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;
+    /**
+     * Remove a pinned tooltip by its instance id.
+     */
+    unpinTooltip: (id: string) => void;
+}
+/**
+ * Toolbar context
+ */
+export declare const ToolbarContext: ReturnType<typeof createContext<ToolbarContextState | null>>;
+/**
+ * Hook to access toolbar context
+ * @throws Error if used outside ToolbarContext provider
+ */
+export declare const useToolbarContext: () => ToolbarContextState;

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

@@ -0,0 +1,23 @@
+import type { VisulimaDevTools } from "../types/global-api.d.ts";
+import type { DevToolbarApp } from "../types/index.d.ts";
+/**
+ * Global DevTools API implementation.
+ */
+export declare const createGlobalAPI: (appManager: {
+    clearNotification: (id: string) => void;
+    getActiveApp: () => DevToolbarApp | undefined;
+    getApps: () => DevToolbarApp[];
+    registerApp: (app: DevToolbarApp) => 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;
+/**
+ * Setup global API on window object
+ * @param api API instance
+ */
+export declare const setupGlobalAPI: (api: VisulimaDevTools) => void;

package/dist/toolbar/helpers.d.ts

@@ -0,0 +1,6 @@
+import type { ServerHelpers } from "../types/app.d.ts";
+/**
+ * Create server helpers for apps
+ * @returns Server helpers instance
+ */
+export declare const createServerHelpers: () => ServerHelpers;

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

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

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

@@ -0,0 +1,13 @@
+import type { DevToolbarAppState } from "../../types/index.d.ts";
+/**
+ * Hook for app management - exposes context app methods directly
+ */
+export declare const useApps: () => {
+    activeAppId: string | null;
+    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;
+};

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

@@ -0,0 +1,94 @@
+/**
+ * Keyboard shortcut bindings
+ */
+export interface KeyBindings {
+    /** Toggle toolbar panel open/closed */
+    toggle: string;
+    /** Close active app / panel */
+    close: string;
+}
+export declare const DEFAULT_KEYBINDINGS: KeyBindings;
+/**
+ * Frame state interface
+ */
+export interface DevToolsFrameState {
+    /**
+     * Close panel on outside click
+     */
+    closeOnOutsideClick: boolean;
+    /**
+     * Panel height as viewport height percentage
+     */
+    height: number;
+    /**
+     * Whether DevTools panel is open in a Picture-in-Picture window
+     */
+    isPip: boolean;
+    /**
+     * Whether this is the first visit (used to show onboarding hint)
+     */
+    isFirstVisit: 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;
+}
+/**
+ * Return type for useFrameState hook
+ */
+export interface UseFrameStateReturn {
+    /**
+     * Current frame state
+     */
+    state: DevToolsFrameState;
+    /**
+     * Update state with partial values
+     */
+    updateState: (value: Partial<DevToolsFrameState>) => void;
+}
+/**
+ * Hook for frame state management.
+ * 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;

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

@@ -0,0 +1,21 @@
+/**
+ * Return type for usePanelVisible hook
+ */
+export interface UsePanelVisibleReturn {
+    /**
+     * Close panel
+     */
+    closePanel: () => void;
+    /**
+     * Whether panel is visible
+     */
+    panelVisible: boolean;
+    /**
+     * Toggle panel visibility
+     */
+    togglePanelVisible: (_?: unknown, newState?: boolean) => void;
+}
+/**
+ * Hook for panel visibility management - converted from Vue DevTools usePanelVisible
+ */
+export declare const usePanelVisible: () => UsePanelVisibleReturn;

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

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

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

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

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

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