@autotracer/dashboard

Runtime dashboard widget for controlling AutoTracer with hotkey support.

Elevator Pitch

Provides a floating corner widget and keyboard shortcuts for starting/stopping React18 and Flow tracers in large applications where console access is impractical.

Unique Selling Point

• Smart Visibility: Hidden by default in TEST/QA, auto-shows when tracer starts, persists preference
• Framework-Agnostic: Vanilla JS/TS widget works with any React version
• Zero Configuration: Works out-of-box with sensible defaults
• Keyboard-First: Global hotkeys for instant control without UI interaction

Installation

pnpm add -D @autotracer/dashboard

Configuration

Via Vite Plugin (Recommended)

// vite.config.ts
import { reactTracer } from "@autotracer/plugin-vite-react18";

export default defineConfig({
  plugins: [
    reactTracer({
      dashboardConfig: {
        enabled: true, // Enable dashboard (default: true)
        hideByDefault: true, // Hide in TEST/QA (default: false)
        position: "bottom-right", // Widget position (default: "bottom-right")
        hotkeys: {
          toggleTracing: "Alt+Shift+T", // Start/stop tracer
          toggleDashboard: "Alt+Shift+D", // Show/hide widget
        },
      },
    }),
  ],
});

Manual Mount

import { mountDashboard } from "@autotracer/dashboard";

// Mount with defaults
mountDashboard();

// Or with custom config
mountDashboard({
  hideByDefault: true,
  position: "bottom-left",
});

Usage

Default Hotkeys

• Alt+Shift+T: Toggle tracing (start/stop)
• Alt+Shift+D: Toggle dashboard visibility

Programmatic Control

// Access via globalThis
globalThis.autoTracer.widget.show();
globalThis.autoTracer.widget.hide();
globalThis.autoTracer.widget.toggle();
globalThis.autoTracer.widget.isVisible();
globalThis.autoTracer.widget.unregisterHotkeys();

Widget UI States

Collapsed (Default)

Small pill in corner showing tracer status:

• 🟢 Green = Tracer running
• ⚫ Gray = Tracer stopped

Click to expand.

Expanded

Panel showing:

• Available tracers (React18, Flow)
• Start/Stop buttons for each
• Current status

Click close (×) to collapse.

Smart Visibility Logic

// First load with hideByDefault: true
// → Widget hidden (TEST/QA environment)

// User presses Alt+Shift+T to start tracer
// → Widget auto-shows + saves preference to localStorage

// Next page reload
// → Widget shows automatically (ignores hideByDefault)

Rationale: Hidden in TEST/QA by default, but once developer uses the tracer, stays visible for convenience.

Position Options

type DashboardPosition =
  | "bottom-right" // Default
  | "bottom-left"
  | "top-right"
  | "top-left";

Theming

Widget auto-detects system color scheme via prefers-color-scheme media query:

• Light theme in light mode
• Dark theme in dark mode

No manual configuration required.

Mobile Support

• Widget works via touch (tap to expand/collapse)
• Hotkeys automatically disabled on mobile
• Responsive design for smaller screens

Islands Architecture Support

The dashboard safely handles multiple mountDashboard() calls, making it ideal for islands architecture:

// Island 1, Island 2, Island 3 all call mountDashboard()
mountDashboard({ /* config */ });

// Result: Only ONE widget mounts (first call wins)
// Subsequent calls are ignored

How it works:

• First island to load → mounts widget and registers hotkeys
• Subsequent islands → detect existing globalThis.autoTracer.widget, skip mounting
• All islands share the same tracer instance (globalThis.autoTracer.flowTracer)
• Single widget controls single tracer, no duplicates

Recommended pattern:

• Configure dashboardConfig in each island's Vite plugin
• Let the first-to-load island mount the dashboard
• All islands get tracer injection, but only one dashboard

API

mountDashboard(config?)

Mount dashboard widget to DOM and register hotkeys.

mountDashboard({
  enabled?: boolean;
  hideByDefault?: boolean;
  position?: DashboardPosition;
  hotkeys?: {
    toggleTracing?: string;
    toggleDashboard?: string;
  };
});

Note: Calling multiple times is safe (duplicate calls are ignored).

WidgetControls

Exposed via globalThis.autoTracer.widget:

interface WidgetControls {
  show(): void;
  hide(): void;
  toggle(): void;
  isVisible(): boolean;
  unregisterHotkeys(): void;
}

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Modern browsers with ES2022 support

License

MIT © Carl Ribbegårdh