@concavejs/devtools 0.0.1-alpha.4

package/dist/store/event-store.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Client-side Event Store
+ *
+ * Maintains a circular buffer of events captured from WebSocket interception
+ * with persistence, export/import, and time-travel capabilities
+ */
+import type { DevToolsEvent, ActiveSubscription, PerformanceMetrics } from "../types";
+export type EventListener = (event: DevToolsEvent) => void;
+export type FocusListener = (eventId: string | null) => void;
+export interface StoreSnapshot {
+    timestamp: number;
+    events: DevToolsEvent[];
+    subscriptions: Array<[number, ActiveSubscription]>;
+}
+export interface ExportedSession {
+    version: string;
+    exportedAt: number;
+    events: DevToolsEvent[];
+    subscriptions: Array<[number, ActiveSubscription]>;
+    metadata: {
+        userAgent: string;
+        url: string;
+    };
+}
+export interface EventStoreOptions {
+    maxEvents?: number;
+    storageScope?: string;
+    enablePersistence?: boolean;
+}
+export declare class EventStore {
+    private events;
+    private maxEvents;
+    private listeners;
+    private focusListeners;
+    private subscriptions;
+    private snapshots;
+    private maxSnapshots;
+    private isPaused;
+    private focusedEventId;
+    private readonly storageKey;
+    private readonly settingsKey;
+    private readonly persistenceEnabled;
+    private recentEventIds;
+    private persistTimer;
+    private settings;
+    private static readonly MIN_EVENTS;
+    private static readonly MAX_EVENTS;
+    constructor(options?: number | EventStoreOptions, legacyStorageScope?: string);
+    /**
+     * Add an event to the store
+     */
+    addEvent(event: DevToolsEvent): void;
+    /**
+     * Subscribe to new events
+     */
+    subscribe(listener: EventListener): () => void;
+    /**
+     * Subscribe to focus/navigation changes across panels
+     */
+    subscribeFocus(listener: FocusListener): () => void;
+    /**
+     * Set the currently focused event (for cross-panel navigation)
+     */
+    setFocusedEventId(eventId: string | null): void;
+    /**
+     * Get focused event id
+     */
+    getFocusedEventId(): string | null;
+    /**
+     * Get all events
+     */
+    getAllEvents(): DevToolsEvent[];
+    /**
+     * Get events by type
+     */
+    getEventsByType<T extends DevToolsEvent>(type: T["type"]): T[];
+    /**
+     * Get recent events
+     */
+    getRecentEvents(count: number): DevToolsEvent[];
+    /**
+     * Get events for a specific function
+     */
+    getEventsByFunction(udfPath: string): DevToolsEvent[];
+    /**
+     * Get active subscriptions
+     */
+    getActiveSubscriptions(): ActiveSubscription[];
+    /**
+     * Get subscription by query ID
+     */
+    getSubscription(queryId: number): ActiveSubscription | undefined;
+    /**
+     * Calculate performance metrics
+     */
+    getPerformanceMetrics(): PerformanceMetrics;
+    /**
+     * Clear all events
+     */
+    clear(): void;
+    /**
+     * Pause event capture
+     */
+    pause(): void;
+    /**
+     * Resume event capture
+     */
+    resume(): void;
+    /**
+     * Check if paused
+     */
+    isPausedState(): boolean;
+    /**
+     * Create a snapshot of current state (for time-travel)
+     */
+    createSnapshot(): void;
+    /**
+     * Restore from a snapshot
+     */
+    restoreSnapshot(timestamp: number): boolean;
+    /**
+     * Get all snapshots
+     */
+    getSnapshots(): StoreSnapshot[];
+    /**
+     * Export session data
+     */
+    exportSession(): ExportedSession;
+    /**
+     * Import session data
+     */
+    importSession(session: ExportedSession): boolean;
+    /**
+     * Save settings
+     */
+    saveSettings(settings: Partial<typeof this.settings>): void;
+    /**
+     * Get settings
+     */
+    getSettings(): typeof this.settings;
+    /**
+     * Whether this store supports local persistence
+     */
+    isPersistenceEnabled(): boolean;
+    /**
+     * Load settings from localStorage
+     */
+    private loadSettings;
+    /**
+     * Persist events to localStorage
+     */
+    private persistEvents;
+    /**
+     * Load persisted events from localStorage
+     */
+    private loadPersistedEvents;
+    /**
+     * Update subscription tracking
+     */
+    private updateSubscription;
+    private sanitizeEvents;
+    private isEventLike;
+    private normalizeMaxEvents;
+}
+export declare function getGlobalEventStore(): EventStore;

package/dist/store/safe-storage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Safe localStorage wrapper that gracefully handles sandboxed iframes,
+ * restrictive CSP, and other environments where localStorage is unavailable.
+ */
+export declare function getItem(key: string): string | null;
+export declare function setItem(key: string, value: string): void;
+export declare function removeItem(key: string): void;

package/dist/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Devtools Event Types
+ *
+ * These types represent the telemetry data captured from the Convex sync protocol
+ */
+export type JSONValue = null | boolean | number | string | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+export type EventType = "query" | "mutation" | "action" | "subscription" | "log" | "auth";
+export type EventStatus = "pending" | "success" | "error";
+export type SubscriptionStatus = "added" | "updated" | "removed";
+/**
+ * Base event interface
+ */
+export interface BaseEvent {
+    id: string;
+    timestamp: number;
+    type: EventType;
+}
+/**
+ * Query execution event (captured from AddQuery + QueryUpdated/QueryFailed)
+ */
+export interface QueryEvent extends BaseEvent {
+    type: "query";
+    queryId: number;
+    udfPath: string;
+    args: JSONValue[];
+    componentPath?: string;
+    status: EventStatus;
+    result?: JSONValue;
+    error?: string;
+    logLines?: string[];
+    duration?: number;
+    /** ID of the mutation that likely triggered this query update */
+    triggeredBy?: string;
+}
+/**
+ * Mutation execution event (captured from MutationRequest + MutationResponse)
+ */
+export interface MutationEvent extends BaseEvent {
+    type: "mutation";
+    requestId: number;
+    udfPath: string;
+    args: JSONValue[];
+    componentPath?: string;
+    status: EventStatus;
+    result?: JSONValue;
+    error?: string;
+    logLines?: string[];
+    duration?: number;
+}
+/**
+ * Action execution event (captured from ActionRequest + ActionResponse)
+ */
+export interface ActionEvent extends BaseEvent {
+    type: "action";
+    requestId: number;
+    udfPath: string;
+    args: JSONValue[];
+    componentPath?: string;
+    status: EventStatus;
+    result?: JSONValue;
+    error?: string;
+    logLines?: string[];
+    duration?: number;
+}
+/**
+ * Subscription event (captured from ModifyQuerySet)
+ */
+export interface SubscriptionEvent extends BaseEvent {
+    type: "subscription";
+    queryId: number;
+    udfPath: string;
+    args: JSONValue[];
+    componentPath?: string;
+    status: SubscriptionStatus;
+    updateCount?: number;
+}
+/**
+ * Log event (extracted from logLines in responses)
+ */
+export interface LogEvent extends BaseEvent {
+    type: "log";
+    level: "log" | "info" | "warn" | "error";
+    message: string;
+    relatedEventId?: string;
+}
+/**
+ * Authentication protocol event (Connect / Authenticate / AuthError / Authenticated)
+ */
+export interface AuthEvent extends BaseEvent {
+    type: "auth";
+    direction: "client" | "server";
+    messageType: string;
+    status: EventStatus;
+    tokenType?: string;
+    error?: string;
+    details?: JSONValue;
+}
+export type DevToolsEvent = QueryEvent | MutationEvent | ActionEvent | SubscriptionEvent | LogEvent | AuthEvent;
+/**
+ * Active subscription tracking
+ */
+export interface ActiveSubscription {
+    queryId: number;
+    udfPath: string;
+    args: JSONValue[];
+    componentPath?: string;
+    addedAt: number;
+    updateCount: number;
+    lastUpdate: number;
+    currentValue?: JSONValue;
+    previousValue?: JSONValue;
+    status: "active" | "error";
+    error?: string;
+}
+/**
+ * Performance metrics
+ */
+export interface PerformanceMetrics {
+    totalQueries: number;
+    totalMutations: number;
+    totalActions: number;
+    avgQueryDuration: number;
+    avgMutationDuration: number;
+    avgActionDuration: number;
+    p50QueryDuration: number;
+    p50MutationDuration: number;
+    p50ActionDuration: number;
+    p90QueryDuration: number;
+    p90MutationDuration: number;
+    p90ActionDuration: number;
+    p95QueryDuration: number;
+    p95MutationDuration: number;
+    p95ActionDuration: number;
+    p99QueryDuration: number;
+    p99MutationDuration: number;
+    p99ActionDuration: number;
+    slowestOperations: Array<{
+        type: "query" | "mutation" | "action";
+        eventId: string;
+        udfPath: string;
+        duration: number;
+        timestamp: number;
+    }>;
+}

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * DevTools package semantic version (source of truth: package.json).
+ */
+export declare const DEVTOOLS_VERSION: string;
+/**
+ * Chrome extension public version.
+ *
+ * Chrome Web Store requires numeric dot-separated version strings.
+ */
+export declare const CHROME_EXTENSION_VERSION: string;

package/dist/vite-plugin/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Vite Plugin for injecting Concave DevTools
+ */
+import type { Plugin } from "vite";
+export interface DevToolsOptions {
+    /**
+     * Enable devtools (default: true in dev mode)
+     */
+    enabled?: boolean;
+    /**
+     * Position of the devtools overlay
+     */
+    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+}
+export declare function concaveDevTools(options?: DevToolsOptions): Plugin;
+export default concaveDevTools;