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

package/dist/types/app.d.ts

@@ -0,0 +1,175 @@
+import type { ComponentType } from "preact";
+import type { NotificationLevel } from "./toolbar.d.ts";
+/**
+ * Server helpers available to apps
+ */
+export interface ServerHelpers {
+    /**
+     * RPC client for calling server functions
+     */
+    rpc: {
+        [K in keyof ServerFunctions]: ServerFunctions[K];
+    };
+}
+/**
+ * Props passed to app tooltip (hover mini-canvas) components.
+ * Keep compact — tooltip components should be lightweight.
+ */
+export interface AppTooltipProps {
+    /**
+     * Server helpers (RPC, etc.)
+     */
+    helpers: ServerHelpers;
+}
+/**
+ * Event target for app communication
+ */
+export interface ToolbarAppEventTarget extends EventTarget {
+    /**
+     * Dispatch a custom event
+     */
+    dispatchEvent: (event: Event) => boolean;
+}
+/**
+ * App view configuration
+ */
+export type AppView = {
+    /**
+     * Render app inline in shadow DOM (default)
+     */
+    type: "inline";
+} | {
+    /**
+     * URL to load in iframe
+     */
+    src: string;
+    /**
+     * Render app in iframe for isolation
+     */
+    type: "iframe";
+};
+/**
+ * Props passed to Preact component apps
+ */
+export interface AppComponentProps {
+    /**
+     * Event target for app communication
+     */
+    eventTarget: ToolbarAppEventTarget;
+    /**
+     * Server helpers (RPC, etc.)
+     */
+    helpers: ServerHelpers;
+}
+/**
+ * Dev toolbar app definition
+ */
+export interface DevToolbarApp {
+    /**
+     * Called before app is toggled off
+     * Return false to prevent closing
+     * @param canvas Shadow root of the app
+     * @returns Whether to allow closing
+     */
+    beforeTogglingOff?: (canvas: ShadowRoot) => boolean | Promise<boolean>;
+    /**
+     * Preact component for rendering (alternative to init)
+     * If provided, this will be used instead of init
+     */
+    component?: ComponentType<AppComponentProps>;
+    /**
+     * When true, this app is automatically activated when the toolbar opens for
+     * the first time (or when no other app has been activated yet).
+     * Only the first registered app with defaultOpen: true is used.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called when the app is unregistered / removed from the toolbar.
+     * Use this for final cleanup (event listeners, timers, subscriptions).
+     * @param canvas Shadow root of the app
+     */
+    destroy?: (canvas: ShadowRoot) => Promise<void> | void;
+    /**
+     * Icon HTML string (SVG)
+     */
+    icon: string;
+    /**
+     * Unique identifier for the app
+     */
+    id: string;
+    /**
+     * Initialize the app when opened (vanilla JS/CSS/HTML)
+     * @param canvas Shadow root to render into
+     * @param eventTarget Event target for app communication
+     * @param helpers Server helpers (RPC, etc.)
+     */
+    init?: (canvas: ShadowRoot, eventTarget: ToolbarAppEventTarget, helpers: ServerHelpers) => void | Promise<void>;
+    /**
+     * Display name of the app
+     */
+    name: string;
+    /**
+     * Action button callback — called when the button is activated (active: false → true).
+     * When present, clicking the toolbar button will NOT open a panel.
+     * Instead the button toggles its active state and calls onClick (activate)
+     * or onDeactivate (deactivate).
+     */
+    onClick?: () => Promise<void> | void;
+    /**
+     * Called when the action button is deactivated (active: true → false).
+     * Only meaningful when onClick is also provided.
+     */
+    onDeactivate?: () => Promise<void> | void;
+    /**
+     * Optional hover tooltip component — renders a compact live preview when the
+     * user hovers over this app's button in the toolbar pill.
+     * The component should be small (≤280px wide) and self-contained.
+     * If omitted, hovering shows the native title tooltip only.
+     */
+    tooltip?: ComponentType<AppTooltipProps>;
+    /**
+     * App rendering mode
+     */
+    view?: AppView;
+}
+/**
+ * Internal app state (extends DevToolbarApp)
+ */
+export interface DevToolbarAppState extends DevToolbarApp {
+    /**
+     * Whether the app is currently active/open
+     */
+    active: boolean;
+    /**
+     * Whether this is a built-in app
+     */
+    builtIn: boolean;
+    /**
+     * Event target for this app
+     */
+    eventTarget: ToolbarAppEventTarget;
+    /**
+     * Notification state
+     */
+    notification: {
+        /**
+         * Notification level
+         */
+        level?: NotificationLevel;
+        /**
+         * Whether notification is active
+         */
+        state: boolean;
+    };
+    /**
+     * App initialization status
+     */
+    status: "ready" | "loading" | "pending" | "error";
+}
+/**
+ * Placeholder for ServerFunctions (defined in rpc.ts)
+ */
+export interface ServerFunctions {
+    [key: string]: (...args: any[]) => Promise<any>;
+}

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

@@ -0,0 +1,91 @@
+import type { DevToolbarApp } from "./app.d.ts";
+import type { DevToolbarHook } from "./hooks.d.ts";
+import type { ServerFunctions } from "./rpc.d.ts";
+import type { ToolbarSettings } from "./toolbar.d.ts";
+/**
+ * Global DevTools API interface.
+ * Exposed as window.__VISULIMA_DEVTOOLS__
+ */
+interface VisulimaDevTools {
+    /**
+     * Clears notification for an app.
+     */
+    clearNotification: (appId: string) => void;
+    /**
+     * Closes the currently active app.
+     */
+    closeApp: () => Promise<void>;
+    /**
+     * Gets the currently active app ID.
+     */
+    getActiveApp: () => string | undefined;
+    /**
+     * Gets all registered apps.
+     */
+    getApps: () => DevToolbarApp[];
+    /**
+     * Gets current toolbar settings.
+     */
+    getSettings: () => ToolbarSettings;
+    /**
+     * Hides the toolbar.
+     */
+    hide: () => void;
+    /**
+     * Hook instance for event subscriptions.
+     */
+    hook: DevToolbarHook;
+    /**
+     * Shows a notification for an app.
+     */
+    notify: (appId: string, level: "info" | "warning" | "error") => void;
+    /**
+     * Opens an app by ID.
+     */
+    openApp: (appId: string) => Promise<void>;
+    /**
+     * Registers a custom app.
+     */
+    registerApp: (app: DevToolbarApp) => void;
+    /**
+     * RPC client for calling server functions.
+     */
+    rpc: ServerFunctions;
+    /**
+     * Directly sets the active state of an action button without invoking callbacks.
+     * Useful for deactivating a button from async work running outside the toolbar.
+     */
+    setAppActive: (appId: string, active: boolean) => void;
+    /**
+     * Shows the toolbar.
+     */
+    show: () => void;
+    /**
+     * Toggles toolbar visibility.
+     */
+    toggle: () => void;
+    /**
+     * Unregisters an app by ID.
+     */
+    unregisterApp: (appId: string) => void;
+    /**
+     * Updates toolbar settings.
+     */
+    updateSettings: (settings: Partial<ToolbarSettings>) => void;
+    /**
+     * Package version.
+     */
+    version: string;
+}
+/**
+ * Global API declaration
+ */
+declare global {
+    interface Window {
+        /**
+         * Visulima DevTools global API.
+         */
+        __VISULIMA_DEVTOOLS__?: VisulimaDevTools;
+    }
+}
+export type { VisulimaDevTools };

package/dist/types/hooks.d.ts

@@ -0,0 +1,86 @@
+import type { DevToolbarApp } from "./app.d.ts";
+import type { TimelineEvent } from "./timeline.d.ts";
+/**
+ * Hook event definitions
+ */
+interface HookEvents {
+    [key: string]: (...args: any[]) => void;
+    /**
+     * App error occurred.
+     * @param error Error object.
+     * @param appId Optional app ID where error occurred.
+     */
+    "app:error": (error: Error, appId?: string) => void;
+    /**
+     * DevTools closed.
+     */
+    "devtools:close": () => void;
+    /**
+     * DevTools initialized.
+     */
+    "devtools:init": () => void;
+    /**
+     * DevTools opened.
+     * @param appId ID of the opened app.
+     */
+    "devtools:open": (appId: string) => void;
+    /**
+     * Timeline event added.
+     * @param event Timeline event.
+     */
+    "timeline:event": (event: TimelineEvent) => void;
+}
+/**
+ * Dev toolbar hook interface.
+ * Exposed as window.__DEV_TOOLBAR_HOOK__
+ */
+interface DevToolbarHook {
+    /**
+     * Adds a timeline event.
+     * @param groupId Timeline group ID.
+     * @param event Timeline event.
+     */
+    addTimelineEvent: (groupId: string, event: TimelineEvent) => void;
+    /**
+     * Emits an event.
+     * @param event Event name.
+     * @param args Event arguments.
+     */
+    emit: <T extends keyof HookEvents>(event: T, ...args: Parameters<HookEvents[T]>) => void;
+    /**
+     * Unsubscribes from an event.
+     * @param event Event name.
+     * @param handler Optional specific handler to remove.
+     */
+    off: <T extends keyof HookEvents>(event: T, handler?: HookEvents[T]) => void;
+    /**
+     * Subscribes to an event.
+     * @param event Event name.
+     * @param handler Event handler.
+     * @returns Unsubscribe function.
+     */
+    on: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => () => void;
+    /**
+     * Subscribes to an event once.
+     * @param event Event name.
+     * @param handler Event handler.
+     */
+    once: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => void;
+    /**
+     * Registers a custom app.
+     * @param app App definition.
+     */
+    registerApp: (app: DevToolbarApp) => void;
+}
+/**
+ * Global hook declaration
+ */
+declare global {
+    interface Window {
+        /**
+         * Dev toolbar hook for library integrations.
+         */
+        __DEV_TOOLBAR_HOOK__?: DevToolbarHook;
+    }
+}
+export type { DevToolbarHook, HookEvents };

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public type exports
+ */
+export type { AccessibilityInfo, Annotation, AnnotationIntent, AnnotationSeverity, AnnotationStatus, BoundingBox, CreateAnnotationData, FrameworkContext, ThreadMessage, UpdateAnnotationData, } from "./annotations.d.ts";
+export type { AppView, DevToolbarApp, DevToolbarAppState, ServerFunctions, ServerHelpers, ToolbarAppEventTarget } from "./app.d.ts";
+export type { VisulimaDevTools } from "./global-api.d.ts";
+export type { DevToolbarHook, HookEvents } from "./hooks.d.ts";
+export type { ChannelFactory, MessageChannel, MessageChannelContext } from "./messaging.d.ts";
+export type { ClientRPCContext, ClientFunctions as RPCClientFunctions, ServerFunctions as RPCServerFunctions, ServerRPCContext } from "./rpc.d.ts";
+export type { TimelineEvent, TimelineEventLevel, TimelineGroup } from "./timeline.d.ts";
+export { DEFAULT_TIMELINE_GROUPS } from "./timeline.d.ts";
+export type { FrameState, NotificationLevel, PositionAnchor, ToolbarPlacement, ToolbarSettings } from "./toolbar.d.ts";
+export { DEFAULT_TOOLBAR_SETTINGS } from "./toolbar.d.ts";

package/dist/types/messaging.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Message channel interface for bidirectional communication
+ */
+export interface MessageChannel<TEvents extends Record<string, (...args: any[]) => void>> {
+    /**
+     * Unsubscribe from an event
+     * @param event Event name
+     * @param handler Optional specific handler to remove
+     */
+    off: <K extends keyof TEvents>(event: K, handler?: TEvents[K]) => void;
+    /**
+     * Subscribe to an event
+     * @param event Event name
+     * @param handler Event handler
+     * @returns Unsubscribe function
+     */
+    on: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => () => void;
+    /**
+     * Subscribe to an event once
+     * @param event Event name
+     * @param handler Event handler
+     */
+    once: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => void;
+    /**
+     * Send a message/event
+     * @param event Event name
+     * @param data Event data
+     */
+    send: <K extends keyof TEvents>(event: K, ...args: Parameters<TEvents[K]>) => void;
+}
+/**
+ * Channel factory function
+ */
+export type ChannelFactory<TEvents extends Record<string, (...args: any[]) => void>> = () => MessageChannel<TEvents>;
+/**
+ * Factory result providing a method to instantiate named message channels.
+ */
+export interface MessageChannelContext<TEvents extends Record<string, (...args: any[]) => void>> {
+    /**
+     * Creates and returns a new channel instance.
+     */
+    createChannel: () => MessageChannel<TEvents>;
+}

package/dist/types/rpc.d.ts

@@ -0,0 +1,137 @@
+import type { ViteDevServer } from "vite";
+import type { StaticAsset } from "../rpc/functions/assets.d.ts";
+import type { SerializableModuleNode } from "../rpc/functions/module-graph.d.ts";
+import type { TailwindConfigResult } from "../rpc/functions/tailwind-config.d.ts";
+import type { Annotation, CreateAnnotationData, UpdateAnnotationData } from "./annotations.d.ts";
+/**
+ * Server-side RPC functions
+ * These can be called from the client
+ */
+export interface ServerFunctions {
+    /**
+     * Extension point for custom server functions
+     */
+    [key: string]: (...args: any[]) => Promise<any>;
+    /**
+     * Create a new annotation
+     * @param data Annotation data (id, timestamps, status are generated server-side)
+     */
+    createAnnotation: (data: CreateAnnotationData) => Promise<Annotation>;
+    /**
+     * Delete an annotation and its screenshot
+     * @param id Annotation ID
+     */
+    deleteAnnotation: (id: string) => Promise<boolean>;
+    /**
+     * Get all annotations
+     */
+    getAnnotations: () => Promise<Annotation[]>;
+    /**
+     * Get module dependency graph
+     */
+    getModuleGraph: () => Promise<SerializableModuleNode[]>;
+    /**
+     * Get a screenshot as a base64 data URL
+     * @param annotationId Annotation ID
+     */
+    getScreenshot: (annotationId: string) => Promise<string | null>;
+    /**
+     * Get all static assets from the public directory
+     */
+    getStaticAssets: () => Promise<StaticAsset[]>;
+    /**
+     * Get full Tailwind CSS theme (default + user overrides)
+     */
+    getTailwindConfig: () => Promise<TailwindConfigResult>;
+    /**
+     * Get Vite configuration
+     */
+    getViteConfig: () => Promise<Record<string, any>>;
+    /**
+     * Open file in editor
+     * @param file File path
+     * @param line Line number (1-based)
+     * @param column Column number (1-based)
+     * @param editor Editor override (e.g. "code", "webstorm") — empty string means auto-detect
+     */
+    openInEditor: (file: string, line?: number, column?: number, editor?: string) => Promise<void>;
+    /**
+     * Read file contents
+     * @param path File path
+     */
+    readFile: (path: string) => Promise<string>;
+    /**
+     * Save a screenshot for an annotation
+     * @param annotationId Annotation ID
+     * @param dataUrl Base64 data URL (PNG, JPEG, WebP, or SVG)
+     * @returns Relative path within .devtoolbar/
+     */
+    saveScreenshot: (annotationId: string, dataUrl: string) => Promise<string>;
+    /**
+     * Update an existing annotation
+     * @param id Annotation ID
+     * @param data Fields to update
+     */
+    updateAnnotation: (id: string, data: UpdateAnnotationData) => Promise<Annotation | null>;
+}
+/**
+ * Client-side RPC functions
+ * These can be called from the server
+ */
+export interface ClientFunctions {
+    [key: string]: (...args: any[]) => void;
+    /**
+     * Notify client of config change
+     * @param config New Vite config
+     */
+    onConfigChange: (config: Record<string, unknown>) => void;
+    /**
+     * Notify client of HMR update
+     * @param payload HMR payload
+     */
+    onHMRUpdate: (payload: unknown) => void;
+    /**
+     * Notify client of module update
+     * @param module Updated module node
+     */
+    onModuleUpdate: (module: SerializableModuleNode) => void;
+}
+/**
+ * RPC context for server-side
+ */
+export interface ServerRPCContext {
+    /**
+     * Call a client function
+     * @param name Function name
+     * @param args Function arguments
+     */
+    callClient: <K extends keyof ClientFunctions>(name: K, ...args: Parameters<ClientFunctions[K]>) => void;
+    /**
+     * Register a server function
+     * @param name Function name
+     * @param fn Function implementation
+     */
+    registerFunction: <K extends keyof ServerFunctions>(name: K, function_: ServerFunctions[K]) => void;
+    /**
+     * Vite dev server instance
+     */
+    server: ViteDevServer;
+}
+/**
+ * RPC context for client-side
+ */
+export interface ClientRPCContext {
+    /**
+     * Call a server function
+     * @param name Function name
+     * @param args Function arguments
+     */
+    callServer: <K extends keyof ServerFunctions>(name: K, ...args: Parameters<ServerFunctions[K]>) => Promise<ReturnType<ServerFunctions[K]>>;
+    /**
+     * Register a client function
+     * @param name Function name
+     * @param function_ Function implementation
+     */
+    registerFunction: <K extends keyof ClientFunctions>(name: K, function_: ClientFunctions[K]) => void;
+}
+export { type StaticAsset } from "../rpc/functions/assets.d.ts";

package/dist/types/timeline.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Severity levels for timeline events.
+ */
+export type TimelineEventLevel = "info" | "warning" | "error";
+/**
+ * A single captured event displayed in the timeline panel.
+ */
+export interface TimelineEvent {
+    /**
+     * Optional event data
+     */
+    data?: Record<string, any>;
+    /**
+     * Optional duration (milliseconds)
+     */
+    duration?: number;
+    /**
+     * Unique event ID
+     */
+    id: string;
+    /**
+     * Event level
+     */
+    level?: TimelineEventLevel;
+    /**
+     * Optional subtitle
+     */
+    subtitle?: string;
+    /**
+     * Timestamp (milliseconds since epoch)
+     */
+    time: number;
+    /**
+     * Event title
+     */
+    title: string;
+}
+/**
+ * A named group that holds related timeline events.
+ */
+export interface TimelineGroup {
+    /**
+     * Group color (hex or CSS color)
+     */
+    color?: string;
+    /**
+     * Events in this group
+     */
+    events: TimelineEvent[];
+    /**
+     * Group ID
+     */
+    id: string;
+    /**
+     * Group label
+     */
+    label: string;
+}
+/**
+ * Default timeline groups
+ */
+export declare const DEFAULT_TIMELINE_GROUPS: ReadonlyArray<TimelineGroup>;

package/dist/types/toolbar.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Toolbar placement options (for backward compatibility)
+ */
+export type ToolbarPlacement = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+/**
+ * Notification levels
+ */
+export type NotificationLevel = "info" | "warning" | "error";
+/**
+ * Position anchor (which edge the toolbar is attached to)
+ * Matches Vue DevTools positioning
+ */
+export type PositionAnchor = "top" | "bottom" | "left" | "right";
+/**
+ * Frame state - matches Vue DevTools DevToolsFrameState
+ * @see https://github.com/vuejs/devtools/blob/main/packages/overlay/src/composables/state.ts
+ */
+export interface FrameState {
+    /**
+     * Horizontal position as percentage (0-100)
+     */
+    left: number;
+    /**
+     * Whether panel is open
+     */
+    open: boolean;
+    /**
+     * Which edge the toolbar is anchored to
+     */
+    position: PositionAnchor;
+    /**
+     * Vertical position as percentage (0-100)
+     */
+    top: number;
+}
+/**
+ * Configuration options controlling the toolbar's initial appearance.
+ */
+export interface ToolbarSettings {
+    /**
+     * Whether toolbar is visible by default
+     */
+    defaultVisible: boolean;
+    /**
+     * Toolbar placement on screen
+     */
+    placement: ToolbarPlacement;
+    /**
+     * Whether to show notifications
+     */
+    showNotifications: boolean;
+}
+/**
+ * Default toolbar settings
+ */
+export declare const DEFAULT_TOOLBAR_SETTINGS: ToolbarSettings;

package/dist/ui/components/alert.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentChildren, JSX } from "preact";
+type AlertVariant = "default" | "destructive" | "info" | "success" | "warning";
+interface AlertProps extends JSX.HTMLAttributes<HTMLDivElement> {
+    children?: ComponentChildren;
+    class?: string;
+    variant?: AlertVariant;
+}
+interface AlertTitleProps extends JSX.HTMLAttributes<HTMLHeadingElement> {
+    children?: ComponentChildren;
+    class?: string;
+}
+interface AlertDescriptionProps extends JSX.HTMLAttributes<HTMLDivElement> {
+    children?: ComponentChildren;
+    class?: string;
+}
+declare const Alert: ({ children, class: className, variant, ...rest }: AlertProps) => JSX.Element;
+declare const AlertTitle: ({ children, class: className, ...rest }: AlertTitleProps) => JSX.Element;
+declare const AlertDescription: ({ children, class: className, ...rest }: AlertDescriptionProps) => JSX.Element;
+export { Alert, AlertDescription, AlertTitle };

package/dist/ui/components/badge.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentChildren, JSX } from "preact";
+type BadgeVariant = "default" | "destructive" | "info" | "outline" | "secondary" | "success" | "warning";
+interface BadgeProps extends JSX.HTMLAttributes<HTMLDivElement> {
+    children?: ComponentChildren;
+    class?: string;
+    variant?: BadgeVariant;
+}
+declare const Badge: ({ children, class: className, variant, ...rest }: BadgeProps) => JSX.Element;
+export default Badge;