@junctionjs/debug 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @junctionjs/debug
+
+In-page debug panel for Junction. Real-time visibility into event flow, consent state, and destination status.
+
+Zero dependencies. Vanilla DOM in a shadow root. Toggles with a keyboard shortcut.
+
+## Features
+
+- **Events tab** — real-time event stream with syntax-highlighted payload expansion, text filtering, color-coded badges
+- **Consent tab** — visual consent state per category with click-to-toggle for testing
+- **Destinations tab** — registered destinations with traffic-light status and per-destination send/error counts
+- **Context tab** — live snapshot of page info, device, UTM params, session, and user identity
+- Status bar with aggregate counters (valid, invalid, sent)
+- Ring buffer retains the last 500 events (configurable)
+- Dark theme, shadow DOM isolated, collapses to a small fab button
+
+## Install
+
+```bash
+npm install @junctionjs/debug
+```
+
+## Usage
+
+```typescript
+import { createDebugPanel } from "@junctionjs/debug";
+
+// Attach to your collector (e.g., window.jct)
+const panel = createDebugPanel(window.jct, {
+  shortcut: "ctrl+shift+j", // keyboard toggle
+  position: "bottom-right",
+  startOpen: false,
+  maxEvents: 500,
+});
+
+// Programmatic control
+panel.open();
+panel.close();
+panel.toggle();
+panel.destroy();
+
+// Access the event store directly
+const entries = panel.store.getEntries();
+const counters = panel.store.getCounters();
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+import { CollectorEvent, Collector } from '@junctionjs/core';
+
+/**
+ * @junctionjs/debug - Event Store
+ *
+ * Ring buffer that captures all collector events for the debug panel.
+ * Subscribes to the collector's event system and maintains an in-memory
+ * log with aggregate counters.
+ */
+
+interface DebugEntry {
+    /** Auto-incrementing ID */
+    id: number;
+    /** ISO timestamp from the collector event */
+    timestamp: string;
+    /** Collector event type */
+    type: CollectorEvent;
+    /** Raw payload from the event */
+    payload: unknown;
+}
+interface DebugCounters {
+    total: number;
+    valid: number;
+    invalid: number;
+    sent: Record<string, number>;
+    errors: Record<string, number>;
+    consentChanges: number;
+    queueFlushes: number;
+}
+interface DebugStore {
+    /** Get all stored entries (newest last) */
+    getEntries: () => DebugEntry[];
+    /** Get entries filtered by type */
+    getByType: (type: CollectorEvent) => DebugEntry[];
+    /** Get aggregate counters */
+    getCounters: () => DebugCounters;
+    /** Clear all entries and reset counters */
+    clear: () => void;
+    /** Subscribe to updates (called on every new entry) */
+    onUpdate: (callback: () => void) => () => void;
+    /** Unsubscribe from all collector events and clean up */
+    destroy: () => void;
+}
+
+/**
+ * @junctionjs/debug - Panel
+ *
+ * DOM construction for the debug overlay. All rendering uses vanilla DOM
+ * inside a shadow root for complete style isolation.
+ *
+ * 4 tabs: Events | Consent | Destinations | Context
+ */
+
+type PanelPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+/**
+ * @junctionjs/debug
+ *
+ * In-page debug overlay for Junction. Shows real-time event flow,
+ * consent state, destination status, and context snapshot.
+ *
+ * Zero dependencies. Vanilla DOM in a shadow root. ~5KB gzipped.
+ *
+ * Usage:
+ *   import { createDebugPanel } from "@junctionjs/debug";
+ *
+ *   const panel = createDebugPanel(window.jct, {
+ *     shortcut: "ctrl+shift+j",
+ *     startOpen: false,
+ *     position: "bottom-right",
+ *   });
+ *
+ *   // Or for Astro integration:
+ *   // The panel auto-injects when debug: true in your junction config.
+ */
+
+interface DebugPanelOptions {
+    /**
+     * Keyboard shortcut to toggle the panel (default: "ctrl+shift+j").
+     * Format: modifier keys joined with "+" followed by a key.
+     * Examples: "ctrl+shift+j", "meta+shift+d", "ctrl+shift+."
+     */
+    shortcut?: string;
+    /** Maximum events to retain in the ring buffer (default: 500) */
+    maxEvents?: number;
+    /** Start with the panel open (default: false) */
+    startOpen?: boolean;
+    /** Panel position on screen (default: "bottom-right") */
+    position?: PanelPosition;
+}
+interface DebugPanelInstance {
+    /** Open the debug panel */
+    open: () => void;
+    /** Close the debug panel */
+    close: () => void;
+    /** Toggle open/close */
+    toggle: () => void;
+    /** Remove the panel from the DOM and unsubscribe from all events */
+    destroy: () => void;
+    /** Access the underlying event store (for programmatic use) */
+    store: DebugStore;
+}
+declare function createDebugPanel(collector: Collector, options?: DebugPanelOptions): DebugPanelInstance;
+
+export { type DebugCounters, type DebugEntry, type DebugPanelInstance, type DebugPanelOptions, type DebugStore, type PanelPosition, createDebugPanel };