@ytspar/devbar 0.0.1 → 1.0.0-canary.2b99e1e

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ytspar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,190 @@
 # @ytspar/devbar
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![npm](https://img.shields.io/npm/v/@ytspar/devbar)](https://www.npmjs.com/package/@ytspar/devbar)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+Development toolbar with Sweetlink integration for browser-based development tools.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Features
 
-## Purpose
+- **Breakpoint indicator**: Shows current Tailwind breakpoint and viewport dimensions
+- **Performance metrics**: FCP, LCP, and total page size
+- **Console badges**: Error and warning counts with click-to-view logs
+- **Screenshot capture**: Save to file or copy to clipboard
+- **AI Design Review**: Send screenshots to Claude for design analysis
+- **Document Outline**: View and export page heading structure
+- **Page Schema**: View JSON-LD, Open Graph, and meta tag data
+- **Sweetlink integration**: Real-time connection to dev server
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ytspar/devbar`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Installation
+
+```bash
+pnpm add @ytspar/devbar
+
+# Or install canary (latest from main)
+pnpm add @ytspar/devbar@canary
+```
+
+## Usage
+
+### Basic Setup (Vanilla JS)
+
+```typescript
+import { initGlobalDevBar } from '@ytspar/devbar';
+
+// Initialize with default options
+initGlobalDevBar();
+
+// Or with custom options
+initGlobalDevBar({
+  position: 'bottom-left',
+  accentColor: '#10b981',
+});
+```
+
+### In a Vite/React Project
+
+```typescript
+// main.ts or App.tsx
+if (import.meta.env.DEV) {
+  import('@ytspar/devbar').then(({ initGlobalDevBar }) => {
+    initGlobalDevBar({
+      position: 'bottom-center',
+      showTooltips: true,
+    });
+  });
+}
+```
+
+### Positions
+
+The devbar can be placed in five positions:
+
+| Position | Description |
+|----------|-------------|
+| `bottom-left` | Bottom left corner (default) - leaves room for other dev tools on the right |
+| `bottom-right` | Bottom right corner |
+| `top-left` | Top left corner |
+| `top-right` | Top right corner |
+| `bottom-center` | Centered at bottom - ideal for focused development, responsive at mobile sizes |
 
-## What is OIDC Trusted Publishing?
+```typescript
+// Example: Center the devbar at the bottom
+initGlobalDevBar({ position: 'bottom-center' });
+```
+
+On mobile viewports (`<640px`), all positions automatically center and the action buttons wrap to a second row.
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+### Configuration Options
 
-## Setup Instructions
+```typescript
+interface GlobalDevBarOptions {
+  /** Position of the devbar. Default: 'bottom-left' */
+  position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'bottom-center';
 
-To properly configure OIDC trusted publishing for this package:
+  /** Primary accent color (CSS color). Default: '#10b981' (emerald) */
+  accentColor?: string;
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+  /** Which metrics to show. Default: all enabled */
+  showMetrics?: {
+    breakpoint?: boolean;  // Tailwind breakpoint indicator
+    fcp?: boolean;         // First Contentful Paint
+    lcp?: boolean;         // Largest Contentful Paint
+    pageSize?: boolean;    // Total transfer size
+  };
 
-## DO NOT USE THIS PACKAGE
+  /** Whether to show the screenshot button. Default: true */
+  showScreenshot?: boolean;
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+  /** Whether to show console error/warning badges. Default: true */
+  showConsoleBadges?: boolean;
 
-## More Information
+  /** Whether to show tooltips on hover. Default: true */
+  showTooltips?: boolean;
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+  /** Size overrides for special layouts */
+  sizeOverrides?: {
+    width?: string;
+    maxWidth?: string;
+    minWidth?: string;
+  };
+}
+```
 
----
+### Example: Minimal DevBar
 
-**Maintained for OIDC setup purposes only**
+```typescript
+initGlobalDevBar({
+  showMetrics: {
+    breakpoint: true,
+    fcp: false,
+    lcp: false,
+    pageSize: false,
+  },
+  showScreenshot: false,
+  showConsoleBadges: true,
+  showTooltips: false,  // Disable tooltips
+});
+```
+
+### Custom Controls
+
+Register custom buttons that appear in the devbar:
+
+```typescript
+import { GlobalDevBar } from '@ytspar/devbar';
+
+// Register a custom control
+GlobalDevBar.registerControl({
+  id: 'my-control',
+  label: 'Reset State',
+  onClick: () => {
+    localStorage.clear();
+    location.reload();
+  },
+  variant: 'warning',  // 'default' | 'warning'
+});
+
+// Unregister when done
+GlobalDevBar.unregisterControl('my-control');
+```
+
+### Cleanup
+
+```typescript
+import { destroyGlobalDevBar } from '@ytspar/devbar';
+
+// Remove the devbar and cleanup listeners
+destroyGlobalDevBar();
+```
+
+## Keyboard Shortcuts
+
+- `Cmd/Ctrl + Shift + S`: Save screenshot to file
+- `Cmd/Ctrl + Shift + C`: Copy screenshot to clipboard
+- `Escape`: Close any open modal/popup
+
+## Integration with Sweetlink
+
+The devbar automatically connects to the Sweetlink WebSocket server (port 9223) for:
+
+- Screenshot saving to the project directory
+- AI-powered design review via Claude
+- Document outline and schema export
+
+When Sweetlink is not running, the devbar still functions but file-saving features are disabled.
+
+## Early Console Capture
+
+Console logs are captured from the moment the devbar module loads, before your app initializes. This catches:
+
+- All `console.log/error/warn/info` calls
+- Errors that occur during hydration
+- Early initialization issues
+
+## Dependencies
+
+- `html2canvas-pro` - Screenshot capture
+
+## License
+
+MIT

package/dist/GlobalDevBar.d.ts

@@ -0,0 +1,318 @@
+/**
+ * GlobalDevBar - Vanilla JS implementation
+ *
+ * A development toolbar that displays breakpoint info, performance stats,
+ * console error/warning counts, and provides screenshot capabilities via Sweetlink.
+ *
+ * This is a vanilla JS replacement for the React-based GlobalDevBar component
+ * to avoid React dependency conflicts in host applications.
+ */
+import { getThemeColors } from './constants.js';
+import type { ConsoleLog, DebugConfig, DevBarControl, GlobalDevBarOptions, OutlineNode, PageSchema, SweetlinkCommand, ThemeMode } from './types.js';
+export type { ConsoleLog, DebugConfig, SweetlinkCommand, OutlineNode, PageSchema, GlobalDevBarOptions, DevBarControl, ThemeMode, };
+export type { DevBarPosition, DevBarSettings, MetricsVisibility } from './settings.js';
+export { ACCENT_COLOR_PRESETS, DEFAULT_SETTINGS, getSettingsManager } from './settings.js';
+interface EarlyConsoleCapture {
+    errorCount: number;
+    warningCount: number;
+    logs: ConsoleLog[];
+    originalConsole: {
+        log: typeof console.log;
+        error: typeof console.error;
+        warn: typeof console.warn;
+        info: typeof console.info;
+    } | null;
+    isPatched: boolean;
+}
+declare const earlyConsoleCapture: EarlyConsoleCapture;
+export declare class GlobalDevBar {
+    private static customControls;
+    private options;
+    private debugConfig;
+    private debug;
+    private container;
+    private ws;
+    private consoleLogs;
+    private sweetlinkConnected;
+    private collapsed;
+    private capturing;
+    private copiedToClipboard;
+    private copiedPath;
+    private lastScreenshot;
+    private designReviewInProgress;
+    private lastDesignReview;
+    private designReviewError;
+    private showDesignReviewConfirm;
+    private apiKeyStatus;
+    private lastOutline;
+    private lastSchema;
+    private savingOutline;
+    private savingSchema;
+    private consoleFilter;
+    private showOutlineModal;
+    private showSchemaModal;
+    private breakpointInfo;
+    private perfStats;
+    private lcpValue;
+    private clsValue;
+    private inpValue;
+    private reconnectAttempts;
+    private readonly currentAppPort;
+    private readonly baseWsPort;
+    private wsVerified;
+    private serverProjectDir;
+    private lastDotPosition;
+    private reconnectTimeout;
+    private screenshotTimeout;
+    private copiedPathTimeout;
+    private designReviewTimeout;
+    private designReviewErrorTimeout;
+    private outlineTimeout;
+    private schemaTimeout;
+    private resizeHandler;
+    private keydownHandler;
+    private fcpObserver;
+    private lcpObserver;
+    private clsObserver;
+    private inpObserver;
+    private destroyed;
+    private themeMode;
+    private themeMediaQuery;
+    private themeMediaHandler;
+    private compactMode;
+    private showSettingsPopover;
+    private overlayElement;
+    private settingsManager;
+    constructor(options?: GlobalDevBarOptions);
+    /**
+     * Get tooltip class name(s) if tooltips are enabled, otherwise empty string
+     */
+    private tooltipClass;
+    /**
+     * Get current error and warning counts from the log array
+     */
+    private getLogCounts;
+    /**
+     * Create a collapsed count badge (used for error/warning counts in minimized state)
+     */
+    private createCollapsedBadge;
+    /**
+     * Register a custom control to be displayed in the devbar
+     */
+    static registerControl(control: DevBarControl): void;
+    /**
+     * Unregister a custom control by ID
+     */
+    static unregisterControl(id: string): void;
+    /**
+     * Get all registered custom controls
+     */
+    static getControls(): DevBarControl[];
+    /**
+     * Clear all custom controls
+     */
+    static clearControls(): void;
+    /**
+     * Initialize and mount the devbar
+     */
+    init(): void;
+    /**
+     * Get the current position
+     */
+    getPosition(): string;
+    /**
+     * Destroy the devbar and cleanup
+     */
+    destroy(): void;
+    private injectStyles;
+    private connectWebSocket;
+    private handleSweetlinkCommand;
+    /**
+     * Handle settings loaded from server
+     */
+    private handleSettingsLoaded;
+    /**
+     * Apply settings to the DevBar state and options
+     */
+    private applySettings;
+    /**
+     * Handle notification state updates with auto-clear timeout
+     */
+    private handleNotification;
+    private setupBreakpointDetection;
+    private setupPerformanceMonitoring;
+    private setupKeyboardShortcuts;
+    private setupTheme;
+    private loadCompactMode;
+    /**
+     * Get the current theme mode
+     */
+    getThemeMode(): ThemeMode;
+    /**
+     * Set the theme mode
+     */
+    setThemeMode(mode: ThemeMode): void;
+    /**
+     * Get the current effective theme colors
+     */
+    getColors(): ReturnType<typeof getThemeColors>;
+    /**
+     * Toggle compact mode
+     */
+    toggleCompactMode(): void;
+    /**
+     * Check if compact mode is enabled
+     */
+    isCompactMode(): boolean;
+    private copyPathToClipboard;
+    private handleScreenshot;
+    private handleDesignReview;
+    /**
+     * Show the design review confirmation modal
+     * Checks API key status first
+     */
+    private showDesignReviewConfirmation;
+    /**
+     * Calculate estimated cost for design review based on viewport size
+     */
+    private calculateCostEstimate;
+    /**
+     * Close the design review confirmation modal
+     */
+    private closeDesignReviewConfirm;
+    /**
+     * Proceed with design review after confirmation
+     */
+    private proceedWithDesignReview;
+    private handleDocumentOutline;
+    private handlePageSchema;
+    private handleSaveOutline;
+    private handleSaveSchema;
+    private clearConsoleLogs;
+    private render;
+    private renderOverlays;
+    private renderDesignReviewConfirmModal;
+    /**
+     * Render content when API key is not configured
+     */
+    private renderApiKeyNotConfiguredContent;
+    /**
+     * Render content when API key is configured (cost estimate and model info)
+     */
+    private renderApiKeyConfiguredContent;
+    private renderConsolePopup;
+    /**
+     * Render console log items into a container
+     */
+    private renderConsoleLogs;
+    private renderOutlineModal;
+    /**
+     * Recursively render outline nodes into a container element
+     */
+    private renderOutlineNodes;
+    private renderSchemaModal;
+    /**
+     * Render a section of schema data (either array or key-value object)
+     */
+    private renderSchemaSection;
+    /**
+     * Render JSON-LD items as formatted code blocks with syntax highlighting
+     */
+    private renderJsonLdItems;
+    /**
+     * Append syntax-highlighted JSON to an element using safe DOM methods
+     * Uses textContent for all text to prevent XSS
+     */
+    private appendHighlightedJson;
+    /**
+     * Render key-value pairs as rows with ellipsis overflow and hover tooltip
+     */
+    private renderKeyValueItems;
+    /**
+     * Render compact mode - single row with essential controls only
+     * Shows: connection dot, error/warn badges, screenshot button, settings gear
+     */
+    private renderCompact;
+    /**
+     * Create the settings gear button
+     */
+    private createSettingsButton;
+    /**
+     * Create the compact mode toggle button with chevron icon
+     */
+    private createCompactToggleButton;
+    /**
+     * Create a settings section with title
+     */
+    private createSettingsSection;
+    /**
+     * Create a toggle switch row
+     */
+    private createToggleRow;
+    /**
+     * Render the settings popover
+     */
+    private renderSettingsPopover;
+    /**
+     * Reset all settings to defaults
+     */
+    private resetToDefaults;
+    private renderCollapsed;
+    private renderExpanded;
+    /** Base styles for tooltip containers */
+    private readonly TOOLTIP_BASE_STYLES;
+    /** Create a tooltip container element */
+    private createTooltipContainer;
+    /** Add a bold title to tooltip (metric name, feature name, etc.) */
+    private addTooltipTitle;
+    /** Add a description paragraph to tooltip */
+    private addTooltipDescription;
+    /** Add a muted uppercase section header to tooltip */
+    private addTooltipSectionHeader;
+    /** Add a colored row with dot + label + value (for thresholds) */
+    private addTooltipColoredRow;
+    /** Add an info row with label + value (for breakpoint details) */
+    private addTooltipInfoRow;
+    /** Position tooltip above the anchor element, adjusting for screen edges */
+    private positionTooltip;
+    /** Attach an HTML tooltip to an element with custom content builder */
+    private attachHtmlTooltip;
+    /** Attach a metric tooltip with title, description, and colored thresholds */
+    private attachMetricTooltip;
+    /** Attach a breakpoint tooltip showing current breakpoint and all breakpoint ranges */
+    private attachBreakpointTooltip;
+    /** Attach a simple info tooltip with title and description */
+    private attachInfoTooltip;
+    /**
+     * Create a console badge for error/warning counts
+     */
+    private createConsoleBadge;
+    private createScreenshotButton;
+    /**
+     * Get the tooltip text for the screenshot button based on current state
+     */
+    private getScreenshotTooltip;
+    /**
+     * Get the tooltip text for the AI review button based on current state
+     */
+    private getAIReviewTooltip;
+    private createAIReviewButton;
+    private createOutlineButton;
+    private createSchemaButton;
+}
+/**
+ * Initialize and mount the GlobalDevBar
+ *
+ * HMR-safe: Uses window-based global that survives module reloads.
+ * If an instance already exists, it will be destroyed and recreated.
+ */
+export declare function initGlobalDevBar(options?: GlobalDevBarOptions): GlobalDevBar;
+/**
+ * Get the current GlobalDevBar instance
+ */
+export declare function getGlobalDevBar(): GlobalDevBar | null;
+/**
+ * Destroy the GlobalDevBar
+ */
+export declare function destroyGlobalDevBar(): void;
+export { earlyConsoleCapture };