@ytspar/devbar 0.0.1 → 1.0.0-canary.e1f65d0

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,185 @@
 # @ytspar/devbar
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Development toolbar with Sweetlink integration for browser-based development tools.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+pnpm add @ytspar/devbar
+```
+
+## 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 |
+
+```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.
+
+### Configuration Options
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+```typescript
+interface GlobalDevBarOptions {
+  /** Position of the devbar. Default: 'bottom-left' */
+  position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'bottom-center';
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+  /** Primary accent color (CSS color). Default: '#10b981' (emerald) */
+  accentColor?: string;
 
-## Purpose
+  /** 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
+  };
 
-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
+  /** Whether to show the screenshot button. Default: true */
+  showScreenshot?: boolean;
 
-## What is OIDC Trusted Publishing?
+  /** Whether to show console error/warning badges. Default: true */
+  showConsoleBadges?: boolean;
 
-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.
+  /** Whether to show tooltips on hover. Default: true */
+  showTooltips?: boolean;
 
-## Setup Instructions
+  /** Size overrides for special layouts */
+  sizeOverrides?: {
+    width?: string;
+    maxWidth?: string;
+    minWidth?: string;
+  };
+}
+```
 
-To properly configure OIDC trusted publishing for this package:
+### Example: Minimal DevBar
 
-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
+```typescript
+initGlobalDevBar({
+  showMetrics: {
+    breakpoint: true,
+    fcp: false,
+    lcp: false,
+    pageSize: false,
+  },
+  showScreenshot: false,
+  showConsoleBadges: true,
+  showTooltips: false,  // Disable tooltips
+});
+```
 
-## DO NOT USE THIS PACKAGE
+### Custom Controls
 
-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
+Register custom buttons that appear in the devbar:
 
-## More Information
+```typescript
+import { GlobalDevBar } from '@ytspar/devbar';
 
-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)
+// 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');
+```
 
-**Maintained for OIDC setup purposes only**
+### 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,201 @@
+/**
+ * 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 type { ConsoleLog, SweetlinkCommand, OutlineNode, PageSchema, GlobalDevBarOptions, DevBarControl } from './types.js';
+export type { ConsoleLog, SweetlinkCommand, OutlineNode, PageSchema, GlobalDevBarOptions, DevBarControl };
+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 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 consoleFilter;
+    private showOutlineModal;
+    private showSchemaModal;
+    private breakpointInfo;
+    private perfStats;
+    private lcpValue;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private screenshotTimeout;
+    private copiedPathTimeout;
+    private designReviewTimeout;
+    private designReviewErrorTimeout;
+    private outlineTimeout;
+    private schemaTimeout;
+    private resizeHandler;
+    private keydownHandler;
+    private fcpObserver;
+    private lcpObserver;
+    private destroyed;
+    private overlayElement;
+    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;
+    /**
+     * Destroy the devbar and cleanup
+     */
+    destroy(): void;
+    private injectStyles;
+    private connectWebSocket;
+    private handleSweetlinkCommand;
+    /**
+     * Handle notification state updates with auto-clear timeout
+     */
+    private handleNotification;
+    private setupBreakpointDetection;
+    private setupPerformanceMonitoring;
+    private setupKeyboardShortcuts;
+    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;
+    private renderCollapsed;
+    private renderExpanded;
+    /**
+     * Create a console badge for error/warning counts
+     */
+    private createConsoleBadge;
+    private createScreenshotButton;
+    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 };