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

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

@@ -0,0 +1,95 @@
+import type { DevToolbarApp } from "./app.d.ts";
+import type { ToolbarSettings } from "./toolbar.d.ts";
+import type { DevToolbarHook } from "./hooks.d.ts";
+import type { ServerFunctions } from "./rpc.d.ts";
+/**
+ * Global DevTools API interface
+ * Exposed as window.__VISULIMA_DEVTOOLS__
+ */
+export interface VisulimaDevTools {
+    /**
+     * Clear notification for an app
+     * @param appId App ID
+     */
+    clearNotification: (appId: string) => void;
+    /**
+     * Close the currently active app
+     */
+    closeApp: () => Promise<void>;
+    /**
+     * Get the currently active app ID
+     * @returns Active app ID or null
+     */
+    getActiveApp: () => string | null;
+    /**
+     * Get all registered apps
+     * @returns Array of app definitions
+     */
+    getApps: () => DevToolbarApp[];
+    /**
+     * Get current toolbar settings
+     * @returns Toolbar settings
+     */
+    getSettings: () => ToolbarSettings;
+    /**
+     * Hide the toolbar
+     */
+    hide: () => void;
+    /**
+     * Hook instance for event subscriptions
+     */
+    hook: DevToolbarHook;
+    /**
+     * Show a notification for an app
+     * @param appId App ID
+     * @param level Notification level
+     */
+    notify: (appId: string, level: "info" | "warning" | "error") => void;
+    /**
+     * Open an app
+     * @param appId App ID to open
+     */
+    openApp: (appId: string) => Promise<void>;
+    /**
+     * Register a custom app
+     * @param app App definition
+     */
+    registerApp: (app: DevToolbarApp) => void;
+    /**
+     * RPC client for calling server functions
+     */
+    rpc: ServerFunctions;
+    /**
+     * Show the toolbar
+     */
+    show: () => void;
+    /**
+     * Toggle toolbar visibility
+     */
+    toggle: () => void;
+    /**
+     * Unregister an app
+     * @param appId App ID to unregister
+     */
+    unregisterApp: (appId: string) => void;
+    /**
+     * Update toolbar settings
+     * @param settings Partial settings to update
+     */
+    updateSettings: (settings: Partial<ToolbarSettings>) => void;
+    /**
+     * Package version
+     */
+    version: string;
+}
+/**
+ * Global API declaration
+ */
+declare global {
+    interface Window {
+        /**
+         * Visulima DevTools global API
+         */
+        __VISULIMA_DEVTOOLS__?: VisulimaDevTools;
+    }
+}

package/dist/types/hooks.d.ts

@@ -0,0 +1,88 @@
+import type { DevToolbarApp } from "./app.d.ts";
+import type { TimelineEvent } from "./timeline.d.ts";
+/**
+ * Hook event definitions
+ */
+export interface HookEvents {
+    /**
+     * Extension point for custom events
+     */
+    [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__
+ */
+export interface DevToolbarHook {
+    /**
+     * Add a timeline event
+     * @param groupId Timeline group ID
+     * @param event Timeline event
+     */
+    addTimelineEvent: (groupId: string, event: TimelineEvent) => void;
+    /**
+     * Emit an event
+     * @param event Event name
+     * @param args Event arguments
+     */
+    emit: <T extends keyof HookEvents>(event: T, ...args: Parameters<HookEvents[T]>) => void;
+    /**
+     * Unsubscribe 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;
+    /**
+     * Subscribe 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;
+    /**
+     * Subscribe to an event once
+     * @param event Event name
+     * @param handler Event handler
+     */
+    once: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => void;
+    /**
+     * Register 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;
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public type exports
+ */
+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>;
+/**
+ * Message channel context
+ */
+export interface MessageChannelContext<TEvents extends Record<string, (...args: any[]) => void>> {
+    /**
+     * Create a new channel instance
+     */
+    createChannel: () => MessageChannel<TEvents>;
+}

package/dist/types/rpc.d.ts

@@ -0,0 +1,95 @@
+import type { ViteDevServer } from "vite";
+import type { SerializableModuleNode } from "../rpc/functions/module-graph.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>;
+    /**
+     * Get module dependency graph
+     */
+    getModuleGraph: () => Promise<SerializableModuleNode[]>;
+    /**
+     * 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)
+     */
+    openInEditor: (file: string, line?: number, column?: number) => Promise<void>;
+    /**
+     * Read file contents
+     * @param path File path
+     */
+    readFile: (path: string) => Promise<string>;
+}
+/**
+ * Client-side RPC functions
+ * These can be called from the server
+ */
+export interface ClientFunctions {
+    /**
+     * Extension point for custom client functions
+     */
+    [key: string]: (...args: any[]) => void;
+    /**
+     * Notify client of config change
+     * @param config New Vite config
+     */
+    onConfigChange: (config: Record<string, any>) => void;
+    /**
+     * Notify client of HMR update
+     * @param payload HMR payload
+     */
+    onHMRUpdate: (payload: any) => 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 fn Function implementation
+     */
+    registerFunction: <K extends keyof ClientFunctions>(name: K, function_: ClientFunctions[K]) => void;
+}

package/dist/types/timeline.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Timeline event level
+ */
+export type TimelineEventLevel = "info" | "warning" | "error";
+/**
+ * Timeline event
+ */
+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;
+}
+/**
+ * Timeline group
+ */
+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;
+}
+/**
+ * Toolbar settings
+ */
+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/icon.d.ts

@@ -0,0 +1,21 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren } from "preact";
+interface IconProps {
+    class?: string;
+    size?: number;
+    /**
+     * CSS data-URI from a `?data-uri&encoding=css` lucide-static import.
+     * Uses CSS mask-image so the icon inherits currentColor from the parent.
+     */
+    src: string;
+}
+/**
+ * Renders a lucide-static icon using CSS mask-image.
+ * Color is driven by the parent element's `color` property (currentColor).
+ *
+ * Usage:
+ *   import xIcon from "lucide-static/icons/x.d.ts";
+ *   <Icon src={xIcon} size={13} />
+ */
+declare const Icon: ({ src, size, class: className }: IconProps) => ComponentChildren;
+export default Icon;

package/dist/utils/cn.d.ts

@@ -0,0 +1,8 @@
+import type { ClassValue } from "clsx";
+/**
+ * Merge Tailwind CSS classes with clsx and tailwind-merge
+ * @param inputs Class values to merge
+ * @returns Merged class string
+ */
+declare const cn: (...inputs: ClassValue[]) => string;
+export default cn;

package/dist/vite-plugin.d.ts

@@ -0,0 +1,106 @@
+import type { Plugin } from "vite";
+import type { DevToolbarApp, ServerFunctions } from "./types/index.d.ts";
+/**
+ * Dev toolbar plugin options
+ */
+export interface DevToolbarOptions {
+    /**
+     * append an import to the module id ending with `appendTo` instead of adding a script into body
+     * useful for projects that do not use html file as an entry
+     *
+     * WARNING: only set this if you know exactly what it does.
+     * @default ''
+     */
+    appendTo?: string | RegExp;
+    /**
+     * Built-in apps to enable
+     */
+    apps?: {
+        [key: string]: boolean | undefined;
+        a11y?: boolean;
+        moduleGraph?: boolean;
+        performance?: boolean;
+        seo?: boolean;
+        settings?: boolean;
+        timeline?: boolean;
+        viteConfig?: boolean;
+    };
+    /**
+     * Whether clicking outside the DevTools panel closes it.
+     * @default true
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * Custom apps to register
+     */
+    customApps?: DevToolbarApp[];
+    /**
+     * Whether toolbar is visible by default
+     */
+    defaultVisible?: boolean;
+    /**
+     * Initial panel height as a percentage of the viewport height (20–95).
+     * @default 60
+     */
+    height?: number;
+    /**
+     * Keyboard shortcut bindings.
+     * These are project-level defaults; users can still override them via the
+     * Settings app (stored in localStorage).
+     */
+    keybindings?: {
+        /** Close active app / panel. @default "Escape" */
+        close?: string;
+        /** Toggle the DevTools panel open/closed. @default "Alt+Shift+D" */
+        toggle?: string;
+    };
+    /**
+     * Auto-hide the toolbar pill after this many milliseconds of inactivity.
+     * Set to -1 to never auto-hide.
+     * @default 5000
+     */
+    minimizePanelInactive?: number;
+    /**
+     * Toolbar placement (coarse shorthand — sets the edge and rough horizontal
+     * alignment of the toolbar pill).
+     * @default "bottom-center"
+     */
+    placement?: "bottom-left" | "bottom-center" | "bottom-right";
+    /**
+     * Which edge of the viewport the toolbar pill is anchored to.
+     * Takes precedence over the edge implied by `placement`.
+     * @default "bottom"
+     */
+    position?: "bottom" | "left" | "right" | "top";
+    /**
+     * Reduce motion for accessibility (disables all CSS animations).
+     * @default false
+     */
+    reduceMotion?: boolean;
+    /**
+     * Only activate the toolbar when the URL contains a specific query parameter.
+     * Useful for staging/production environments where you want opt-in debugging.
+     * @example requireUrlFlag: true, urlFlagName: 'debug' → toolbar only shows when URL has ?debug=true
+     * @default false
+     */
+    requireUrlFlag?: boolean;
+    /**
+     * Custom server RPC functions
+     */
+    serverFunctions?: Partial<ServerFunctions>;
+    /**
+     * The URL query parameter name used when requireUrlFlag is true.
+     * @default 'devtools'
+     */
+    urlFlagName?: string;
+    /**
+     * Initial panel width as a percentage of the viewport width (20–95).
+     * Applies when position is "left" or "right".
+     * @default 80
+     */
+    width?: number;
+}
+/**
+ * Dev toolbar Vite plugin
+ */
+export declare const devToolbar: (options?: DevToolbarOptions) => Plugin;

package/dist/vite-plugin.js

@@ -0,0 +1,2 @@
+var g=Object.defineProperty;var p=(e,r)=>g(e,"name",{value:r,configurable:!0});import{createRequire as b}from"node:module";import{normalizePath as $}from"vite";import{createServerRPCContext as j}from"./packem_shared/createServerRPCContext-BVSesPXu.js";const h=b(import.meta.url),s=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,u=p(e=>{if(typeof s<"u"&&s.versions&&s.versions.node){const[r,o]=s.versions.node.split(".").map(Number);if(r>22||r===22&&o>=3||r===20&&o>=16)return s.getBuiltinModule(e)}return h(e)},"__cjs_getBuiltinModule"),y=u("node:fs"),_=u("node:path"),{fileURLToPath:T}=u("node:url");var P=Object.defineProperty,c=p((e,r)=>P(e,"name",{value:r,configurable:!0}),"o");const F=c(()=>$(_.dirname(T(import.meta.url))),"getDevToolbarPath"),C=c(e=>e.replace(/\?.*$/,""),"removeUrlQuery"),d="?__visulima-dev-toolbar-resource",f="virtual:visulima-dev-toolbar-options",m=`\0${f}`,a="virtual:visulima-dev-toolbar-path:",x=c((e={})=>{const r=F();let o;return{apply:"serve",configResolved(t){o=t},configureServer(t){j(t,e.serverFunctions),t.ws.on("connection",()=>{t.ws.send({event:"dev-toolbar:init",type:"custom"})})},enforce:"pre",async load(t){if(t===m)return`export default ${JSON.stringify({apps:{a11y:e.apps?.a11y??!0,moduleGraph:e.apps?.moduleGraph??!0,performance:e.apps?.performance??!0,seo:e.apps?.seo??!0,settings:e.apps?.settings??!0,timeline:e.apps?.timeline??!0,viteConfig:e.apps?.viteConfig??!0},base:o.base,closeOnOutsideClick:e.closeOnOutsideClick??!0,defaultVisible:e.defaultVisible??!0,height:e.height??60,keybindings:e.keybindings??{},minimizePanelInactive:e.minimizePanelInactive??5e3,placement:e.placement??"bottom-center",position:e.position??"bottom",reduceMotion:e.reduceMotion??!1,requireUrlFlag:e.requireUrlFlag??!1,urlFlagName:e.urlFlagName??"devtools",width:e.width??80})};`;if(t.endsWith(d)){const n=C(t);return this.addWatchFile(n),await y.promises.readFile(n,"utf8")}},name:"@visulima/dev-toolbar",resolveId(t){if(t===f)return m;if(t.startsWith(a))return`${t.replace(a,`${r}/`)}${d}`},transform(t,n,v){if(v?.ssr)return;const{appendTo:i}=e,l=n.split("?",2)[0];if(i&&l&&(typeof i=="string"&&l.endsWith(i)||i instanceof RegExp&&i.test(l)))return`import '${a}client/overlay.js';
+${t}`},transformIndexHtml(){return e.appendTo?void 0:{html:"",tags:[{attrs:{src:`${o.base||"/"}@id/${a}client/overlay.js`,type:"module"},injectTo:"head-prepend",tag:"script"}]}}}},"devToolbar");export{x as devToolbar};