adonisjs-server-stats 1.5.3 → 1.6.1

package/dist/src/controller/api_controller.d.ts

@@ -0,0 +1,101 @@
+import type { DataAccess, ListOptions, PaginatedResult } from '../data/data_access.js';
+import type { EventRecord, QueryRecord, RouteRecord, TraceRecord } from '../debug/types.js';
+/**
+ * Unified API controller for all data resource endpoints.
+ *
+ * Delegates every read operation to the {@link DataAccess} abstraction layer,
+ * which transparently routes to either the in-memory {@link DebugStore}
+ * (ring buffers) or the persistent {@link DashboardStore} (SQLite),
+ * depending on availability.
+ *
+ * This controller is intentionally **transport-agnostic** — it knows
+ * nothing about HTTP, `HttpContext`, or response formatting. Route
+ * handlers in {@link registerAllRoutes} call these methods and write
+ * the result to the response themselves.
+ *
+ * @example
+ * ```ts
+ * const api = new ApiController(dataAccess)
+ * const result = await api.getQueries({ page: 1, perPage: 25, search: 'users' })
+ * // → { data: [...], meta: { total, page, perPage, lastPage } }
+ * ```
+ */
+export declare class ApiController {
+    private data;
+    constructor(data: DataAccess);
+    /**
+     * Paginated list of captured SQL queries.
+     *
+     * Supports full-text search across `sql`, `model`, and `connection`
+     * fields, plus optional filter parameters forwarded to the underlying
+     * store (e.g. `durationMin`, `method`, `connection`).
+     */
+    getQueries(opts?: ListOptions): Promise<PaginatedResult<QueryRecord>>;
+    /**
+     * Aggregate query statistics from the in-memory ring buffer.
+     *
+     * Returns total count, number of slow queries, duplicate count,
+     * and the average execution duration.
+     *
+     * **Note:** This always reads from the {@link DebugStore} because
+     * summary metrics are computed in-memory and not persisted.
+     */
+    getQuerySummary(): {
+        total: number;
+        slow: number;
+        duplicates: number;
+        avgDuration: number;
+    };
+    /**
+     * Paginated list of captured application events.
+     *
+     * Supports full-text search on the event name.
+     */
+    getEvents(opts?: ListOptions): Promise<PaginatedResult<EventRecord>>;
+    /**
+     * Paginated list of captured emails.
+     *
+     * HTML and text bodies are stripped from the list response to keep
+     * payloads lightweight. Use {@link getEmailPreview} for the full body.
+     */
+    getEmails(opts?: ListOptions): Promise<PaginatedResult>;
+    /**
+     * Get the HTML body of a single email for iframe preview rendering.
+     *
+     * Returns the full HTML string, or falls back to the plain-text body.
+     * Returns `null` when the email is not found.
+     */
+    getEmailPreview(id: number, source?: 'memory' | 'auto'): Promise<string | null>;
+    /**
+     * Paginated list of captured request traces.
+     *
+     * Span arrays are stripped from the list response to keep payloads
+     * lightweight. Use {@link getTraceDetail} for the full span tree.
+     */
+    getTraces(opts?: ListOptions): Promise<PaginatedResult>;
+    /**
+     * Get a single trace with its full span tree.
+     *
+     * Returns `null` when the trace is not found or tracing is disabled.
+     */
+    getTraceDetail(id: number, source?: 'memory' | 'auto'): Promise<TraceRecord | null>;
+    /**
+     * Get the registered route table.
+     *
+     * Routes are always read from the in-memory {@link DebugStore} because
+     * they are static boot-time data that is never persisted to SQLite.
+     *
+     * Supports optional search filtering across pattern, handler, name,
+     * and HTTP method fields.
+     */
+    getRoutes(search?: string): PaginatedResult<RouteRecord>;
+    /**
+     * Paginated list of log entries.
+     *
+     * When the dashboard store is available, logs are read from SQLite
+     * with full server-side filtering. Otherwise, falls back to reading
+     * the last 256 KB of the application log file from the filesystem.
+     */
+    getLogs(opts?: ListOptions): Promise<PaginatedResult>;
+}
+//# sourceMappingURL=api_controller.d.ts.map

package/dist/src/controller/api_controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api_controller.d.ts","sourceRoot":"","sources":["../../../src/controller/api_controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACtF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE3F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAMpC;;;;;;OAMG;IACG,UAAU,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;IAI/E;;;;;;;;OAQG;IACH,eAAe,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;IAQ3F;;;;OAIG;IACG,SAAS,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;IAQ9E;;;;;OAKG;IACG,SAAS,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjE;;;;;OAKG;IACG,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQrF;;;;;OAKG;IACG,SAAS,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjE;;;;OAIG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQzF;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC;IAQxD;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;CAGhE"}

package/dist/src/controller/api_controller.js

@@ -0,0 +1,131 @@
+/**
+ * Unified API controller for all data resource endpoints.
+ *
+ * Delegates every read operation to the {@link DataAccess} abstraction layer,
+ * which transparently routes to either the in-memory {@link DebugStore}
+ * (ring buffers) or the persistent {@link DashboardStore} (SQLite),
+ * depending on availability.
+ *
+ * This controller is intentionally **transport-agnostic** — it knows
+ * nothing about HTTP, `HttpContext`, or response formatting. Route
+ * handlers in {@link registerAllRoutes} call these methods and write
+ * the result to the response themselves.
+ *
+ * @example
+ * ```ts
+ * const api = new ApiController(dataAccess)
+ * const result = await api.getQueries({ page: 1, perPage: 25, search: 'users' })
+ * // → { data: [...], meta: { total, page, perPage, lastPage } }
+ * ```
+ */
+export class ApiController {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    // ===========================================================================
+    // Queries
+    // ===========================================================================
+    /**
+     * Paginated list of captured SQL queries.
+     *
+     * Supports full-text search across `sql`, `model`, and `connection`
+     * fields, plus optional filter parameters forwarded to the underlying
+     * store (e.g. `durationMin`, `method`, `connection`).
+     */
+    async getQueries(opts = {}) {
+        return this.data.getQueries(opts);
+    }
+    /**
+     * Aggregate query statistics from the in-memory ring buffer.
+     *
+     * Returns total count, number of slow queries, duplicate count,
+     * and the average execution duration.
+     *
+     * **Note:** This always reads from the {@link DebugStore} because
+     * summary metrics are computed in-memory and not persisted.
+     */
+    getQuerySummary() {
+        return this.data.getQuerySummary();
+    }
+    // ===========================================================================
+    // Events
+    // ===========================================================================
+    /**
+     * Paginated list of captured application events.
+     *
+     * Supports full-text search on the event name.
+     */
+    async getEvents(opts = {}) {
+        return this.data.getEvents(opts);
+    }
+    // ===========================================================================
+    // Emails
+    // ===========================================================================
+    /**
+     * Paginated list of captured emails.
+     *
+     * HTML and text bodies are stripped from the list response to keep
+     * payloads lightweight. Use {@link getEmailPreview} for the full body.
+     */
+    async getEmails(opts = {}) {
+        return this.data.getEmails(opts);
+    }
+    /**
+     * Get the HTML body of a single email for iframe preview rendering.
+     *
+     * Returns the full HTML string, or falls back to the plain-text body.
+     * Returns `null` when the email is not found.
+     */
+    async getEmailPreview(id, source) {
+        return this.data.getEmailPreview(id, source);
+    }
+    // ===========================================================================
+    // Traces
+    // ===========================================================================
+    /**
+     * Paginated list of captured request traces.
+     *
+     * Span arrays are stripped from the list response to keep payloads
+     * lightweight. Use {@link getTraceDetail} for the full span tree.
+     */
+    async getTraces(opts = {}) {
+        return this.data.getTraces(opts);
+    }
+    /**
+     * Get a single trace with its full span tree.
+     *
+     * Returns `null` when the trace is not found or tracing is disabled.
+     */
+    async getTraceDetail(id, source) {
+        return this.data.getTraceDetail(id, source);
+    }
+    // ===========================================================================
+    // Routes
+    // ===========================================================================
+    /**
+     * Get the registered route table.
+     *
+     * Routes are always read from the in-memory {@link DebugStore} because
+     * they are static boot-time data that is never persisted to SQLite.
+     *
+     * Supports optional search filtering across pattern, handler, name,
+     * and HTTP method fields.
+     */
+    getRoutes(search) {
+        return this.data.getRoutes(search);
+    }
+    // ===========================================================================
+    // Logs
+    // ===========================================================================
+    /**
+     * Paginated list of log entries.
+     *
+     * When the dashboard store is available, logs are read from SQLite
+     * with full server-side filtering. Otherwise, falls back to reading
+     * the last 256 KB of the application log file from the filesystem.
+     */
+    async getLogs(opts = {}) {
+        return this.data.getLogs(opts);
+    }
+}

package/dist/src/controller/debug_controller.d.ts

@@ -1,16 +1,20 @@
+import type { DashboardStore } from '../dashboard/dashboard_store.js';
 import type { DebugStore } from '../debug/debug_store.js';
+import type { StatsEngine } from '../engine/stats_engine.js';
+import type { ResolvedServerStatsConfig } from '../types.js';
 import type { HttpContext } from '@adonisjs/core/http';
+interface DiagnosticsDeps {
+    getEngine?: () => StatsEngine | null;
+    getDashboardStore?: () => DashboardStore | null;
+    getProviderDiagnostics?: () => Record<string, unknown>;
+}
 export default class DebugController {
     private store;
-    private logPath;
-    constructor(store: DebugStore, logPath: string);
-    queries({ response }: HttpContext): Promise<void>;
-    events({ response }: HttpContext): Promise<void>;
-    routes({ response }: HttpContext): Promise<void>;
-    emails({ response }: HttpContext): Promise<void>;
-    emailPreview({ params, response }: HttpContext): Promise<void>;
-    traces({ response }: HttpContext): Promise<void>;
-    traceDetail({ params, response }: HttpContext): Promise<void>;
-    logs({ response }: HttpContext): Promise<void>;
+    private serverConfig?;
+    private diagnosticsDeps;
+    constructor(store: DebugStore, serverConfig?: ResolvedServerStatsConfig | undefined, diagnosticsDeps?: DiagnosticsDeps);
+    config({ response }: HttpContext): Promise<void>;
+    diagnostics({ response }: HttpContext): Promise<void>;
 }
+export {};
 //# sourceMappingURL=debug_controller.d.ts.map

package/dist/src/controller/debug_controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug_controller.d.ts","sourceRoot":"","sources":["../../../src/controller/debug_controller.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAWtD,MAAM,CAAC,OAAO,OAAO,eAAe;IAIhC,OAAO,CAAC,KAAK;IAHf,OAAO,CAAC,OAAO,CAAQ;gBAGb,KAAK,EAAE,UAAU,EACzB,OAAO,EAAE,MAAM;IAKX,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW;IAMjC,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW;IAKhC,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW;IAKhC,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW;IAOhC,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,WAAW;IAS9C,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW;IAahC,WAAW,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,WAAW;IAY7C,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW;CAgDrC"}
+{"version":3,"file":"debug_controller.d.ts","sourceRoot":"","sources":["../../../src/controller/debug_controller.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAC5D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,UAAU,eAAe;IACvB,SAAS,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;IACpC,iBAAiB,CAAC,EAAE,MAAM,cAAc,GAAG,IAAI,CAAA;IAC/C,sBAAsB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvD;AAED,MAAM,CAAC,OAAO,OAAO,eAAe;IAIhC,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,YAAY,CAAC;IAJvB,OAAO,CAAC,eAAe,CAAiB;gBAG9B,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,yBAAyB,YAAA,EAChD,eAAe,CAAC,EAAE,eAAe;IAK7B,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW;IAkDhC,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW;CA+D5C"}

package/dist/src/controller/debug_controller.js

@@ -1,116 +1,110 @@
-import { readFile, stat } from 'node:fs/promises';
-const LEVEL_NAMES = {
-    10: 'trace',
-    20: 'debug',
-    30: 'info',
-    40: 'warn',
-    50: 'error',
-    60: 'fatal',
-};
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
 export default class DebugController {
     store;
-    logPath;
-    constructor(store, logPath) {
+    serverConfig;
+    diagnosticsDeps;
+    constructor(store, serverConfig, diagnosticsDeps) {
         this.store = store;
-        this.logPath = logPath;
+        this.serverConfig = serverConfig;
+        this.diagnosticsDeps = diagnosticsDeps ?? {};
     }
-    async queries({ response }) {
-        const queries = this.store.queries.getLatest(500);
-        const summary = this.store.queries.getSummary();
-        return response.json({ queries, summary });
+    async config({ response }) {
+        const cfg = this.serverConfig;
+        const toolbarConfig = cfg?.devToolbar;
+        // Derive feature flags from the actual config
+        const rawCollectors = cfg?.collectors;
+        const collectorNames = new Set(Array.isArray(rawCollectors) ? rawCollectors.map((c) => c.name) : []);
+        const features = {
+            statsBar: true,
+            debugPanel: !!toolbarConfig?.enabled,
+            dashboard: !!toolbarConfig?.dashboard,
+            tracing: !!toolbarConfig?.tracing,
+            process: collectorNames.has('process'),
+            system: collectorNames.has('system'),
+            http: collectorNames.has('http'),
+            db: collectorNames.has('db_pool'),
+            redis: collectorNames.has('redis'),
+            queues: collectorNames.has('queue'),
+            cache: collectorNames.has('redis'),
+            app: collectorNames.has('app'),
+            log: collectorNames.has('log'),
+            emails: !!toolbarConfig?.enabled,
+        };
+        // Custom panes from config
+        const customPanes = toolbarConfig?.panes ?? [];
+        // Endpoint paths
+        const debugEndpoint = toolbarConfig?.debugEndpoint ?? '/admin/api/debug';
+        const dashboardPath = toolbarConfig?.dashboardPath ?? '/__stats';
+        const statsEndpoint = typeof cfg?.endpoint === 'string' ? cfg.endpoint : '/admin/api/server-stats';
+        const endpoints = {
+            stats: statsEndpoint,
+            debug: debugEndpoint,
+            dashboard: dashboardPath,
+        };
+        // Transmit config
+        const transmit = {
+            channelName: cfg?.channelName ?? 'admin/server-stats',
+        };
+        return response.json({ features, customPanes, endpoints, transmit });
     }
-    async events({ response }) {
-        const events = this.store.events.getLatest(200);
-        return response.json({ events, total: this.store.events.getTotalCount() });
-    }
-    async routes({ response }) {
-        const routes = this.store.routes.getRoutes();
-        return response.json({ routes, total: this.store.routes.getRouteCount() });
-    }
-    async emails({ response }) {
-        const emails = this.store.emails.getLatest(100);
-        // Strip html/text from list response to keep it lightweight
-        const stripped = emails.map(({ html, text, ...rest }) => rest);
-        return response.json({ emails: stripped, total: this.store.emails.getTotalCount() });
-    }
-    async emailPreview({ params, response }) {
-        const id = Number(params.id);
-        const html = this.store.emails.getEmailHtml(id);
-        if (!html) {
-            return response.notFound({ error: 'Email not found' });
+    async diagnostics({ response }) {
+        const engine = this.diagnosticsDeps.getEngine?.();
+        const dashboardStore = this.diagnosticsDeps.getDashboardStore?.();
+        const providerDiag = this.diagnosticsDeps.getProviderDiagnostics?.() ?? {};
+        // Package version — read from disk since createRequire resolves from
+        // the compiled output directory where ../../package.json doesn't exist.
+        let packageVersion = 'unknown';
+        try {
+            const pkgPath = fileURLToPath(new URL('../../../package.json', import.meta.url));
+            const pkgJson = JSON.parse(await readFile(pkgPath, 'utf-8'));
+            packageVersion = pkgJson.version;
         }
-        return response.header('Content-Type', 'text/html; charset=utf-8').send(html);
-    }
-    async traces({ response }) {
-        if (!this.store.traces) {
-            return response.json({ traces: [], total: 0 });
+        catch {
+            // Fallback
         }
-        const traces = this.store.traces.getLatest(100);
-        // Strip spans from list view to keep it lightweight
-        const list = traces.map(({ spans, warnings, ...rest }) => ({
-            ...rest,
-            warningCount: warnings.length,
-        }));
-        return response.json({ traces: list, total: this.store.traces.getTotalCount() });
-    }
-    async traceDetail({ params, response }) {
-        if (!this.store.traces) {
-            return response.notFound({ error: 'Tracing not enabled' });
+        // AdonisJS version
+        let adonisVersion = 'unknown';
+        try {
+            const { createRequire } = await import('node:module');
+            const require = createRequire(import.meta.url);
+            const adonisPkg = require('@adonisjs/core/package.json');
+            adonisVersion = adonisPkg.version;
         }
-        const id = Number(params.id);
-        const trace = this.store.traces.getTrace(id);
-        if (!trace) {
-            return response.notFound({ error: 'Trace not found' });
+        catch {
+            // Not installed or not resolvable
         }
-        return response.json(trace);
-    }
-    async logs({ response }) {
-        try {
-            const stats = await stat(this.logPath);
-            // Only read last 256KB to keep response fast
-            const maxBytes = 256 * 1024;
-            let content;
-            if (stats.size > maxBytes) {
-                const { createReadStream } = await import('node:fs');
-                const stream = createReadStream(this.logPath, {
-                    start: stats.size - maxBytes,
-                    encoding: 'utf-8',
-                });
-                const chunks = [];
-                for await (const chunk of stream) {
-                    chunks.push(chunk);
-                }
-                content = chunks.join('');
-                // Skip first potentially incomplete line
-                const firstNewline = content.indexOf('\n');
-                if (firstNewline !== -1)
-                    content = content.slice(firstNewline + 1);
+        // Collector health + configs
+        const healthList = engine?.getCollectorHealth() ?? [];
+        const configList = engine?.getCollectorConfigs() ?? [];
+        const configMap = new Map(configList.map((c) => [c.name, c.config]));
+        const collectors = healthList.map((h) => ({
+            ...h,
+            config: configMap.get(h.name) ?? {},
+        }));
+        // Buffer stats
+        const buffers = this.store.getBufferStats();
+        // Storage stats (if dashboard is active)
+        let storage = null;
+        if (dashboardStore) {
+            try {
+                storage = await dashboardStore.getStorageStats();
             }
-            else {
-                content = await readFile(this.logPath, 'utf-8');
+            catch {
+                // Dashboard store not ready
             }
-            const entries = content
-                .trim()
-                .split('\n')
-                .filter(Boolean)
-                .map((line) => {
-                try {
-                    const entry = JSON.parse(line);
-                    return {
-                        ...entry,
-                        levelName: LEVEL_NAMES[entry.level] || 'unknown',
-                        timestamp: new Date(entry.time).toISOString(),
-                    };
-                }
-                catch {
-                    return null;
-                }
-            })
-                .filter(Boolean);
-            return response.json(entries);
-        }
-        catch {
-            return response.json([]);
         }
+        return response.json({
+            package: {
+                version: packageVersion,
+                nodeVersion: process.version,
+                adonisVersion,
+                uptime: process.uptime(),
+            },
+            ...providerDiag,
+            collectors,
+            buffers,
+            storage,
+        });
     }
 }

package/dist/src/core/theme.d.ts

@@ -0,0 +1,42 @@
+/**
+ * localStorage key for persisted theme preference.
+ */
+export declare const STORAGE_KEY = "ss-dash-theme";
+/**
+ * The two supported theme values.
+ */
+export type Theme = 'dark' | 'light';
+/**
+ * Read the current theme preference.
+ *
+ * Resolution order:
+ * 1. Explicit value stored in `localStorage` under {@link STORAGE_KEY}.
+ * 2. System preference via `prefers-color-scheme` media query.
+ * 3. Falls back to `'light'` if neither is available (e.g. SSR).
+ */
+export declare function getTheme(): Theme;
+/**
+ * Persist a theme preference to `localStorage` and notify
+ * all in-page listeners via a custom DOM event.
+ *
+ * Other tabs will be notified via the native `storage` event,
+ * which listeners created by {@link onThemeChange} also handle.
+ */
+export declare function setTheme(theme: Theme): void;
+/**
+ * Toggle the current theme and persist the new value.
+ *
+ * @returns The newly active theme.
+ */
+export declare function toggleTheme(): Theme;
+/**
+ * Subscribe to theme changes from:
+ * - Same-tab components (via custom {@link THEME_CHANGE_EVENT} event)
+ * - Other tabs (via native `storage` event)
+ * - System preference changes (via `prefers-color-scheme` media query)
+ *
+ * @param callback - Invoked with the new theme value whenever it changes.
+ * @returns An unsubscribe function that removes all listeners.
+ */
+export declare function onThemeChange(callback: (theme: Theme) => void): () => void;
+//# sourceMappingURL=theme.d.ts.map

package/dist/src/core/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../src/core/theme.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,WAAW,kBAAkB,CAAA;AAa1C;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,OAAO,CAAA;AAEpC;;;;;;;GAOG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAUhC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAQ3C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,KAAK,CAKnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CA6C1E"}

package/dist/src/core/theme.js

@@ -0,0 +1,115 @@
+// ---------------------------------------------------------------------------
+// Theme state management
+// ---------------------------------------------------------------------------
+/**
+ * localStorage key for persisted theme preference.
+ */
+export const STORAGE_KEY = 'ss-dash-theme';
+/**
+ * Custom DOM event name used to synchronize theme changes
+ * across multiple component trees within the same tab.
+ *
+ * The native `storage` event only fires in *other* tabs, so
+ * components rendered as separate React/Vue roots on the same
+ * page (e.g. StatsBar and DebugPanel) would never learn about
+ * each other's changes. This custom event fills that gap.
+ */
+const THEME_CHANGE_EVENT = 'ss-theme-change';
+/**
+ * Read the current theme preference.
+ *
+ * Resolution order:
+ * 1. Explicit value stored in `localStorage` under {@link STORAGE_KEY}.
+ * 2. System preference via `prefers-color-scheme` media query.
+ * 3. Falls back to `'light'` if neither is available (e.g. SSR).
+ */
+export function getTheme() {
+    if (typeof window === 'undefined')
+        return 'light';
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'dark' || stored === 'light')
+        return stored;
+    if (window.matchMedia?.('(prefers-color-scheme: dark)').matches) {
+        return 'dark';
+    }
+    return 'light';
+}
+/**
+ * Persist a theme preference to `localStorage` and notify
+ * all in-page listeners via a custom DOM event.
+ *
+ * Other tabs will be notified via the native `storage` event,
+ * which listeners created by {@link onThemeChange} also handle.
+ */
+export function setTheme(theme) {
+    if (typeof window === 'undefined')
+        return;
+    localStorage.setItem(STORAGE_KEY, theme);
+    // Dispatch a same-tab custom event so that all useTheme() /
+    // useTheme composable instances re-render immediately.
+    // The native `storage` event only fires in *other* tabs.
+    window.dispatchEvent(new CustomEvent(THEME_CHANGE_EVENT, { detail: theme }));
+}
+/**
+ * Toggle the current theme and persist the new value.
+ *
+ * @returns The newly active theme.
+ */
+export function toggleTheme() {
+    const current = getTheme();
+    const next = current === 'dark' ? 'light' : 'dark';
+    setTheme(next);
+    return next;
+}
+/**
+ * Subscribe to theme changes from:
+ * - Same-tab components (via custom {@link THEME_CHANGE_EVENT} event)
+ * - Other tabs (via native `storage` event)
+ * - System preference changes (via `prefers-color-scheme` media query)
+ *
+ * @param callback - Invoked with the new theme value whenever it changes.
+ * @returns An unsubscribe function that removes all listeners.
+ */
+export function onThemeChange(callback) {
+    if (typeof window === 'undefined')
+        return () => { };
+    // Listen for same-tab theme changes via custom event.
+    // This is the primary in-page synchronization mechanism
+    // (mirrors the old vanilla JS `window.__ssApplyBarTheme()` pattern).
+    const handleCustom = (event) => {
+        const theme = event.detail;
+        if (theme === 'dark' || theme === 'light') {
+            callback(theme);
+        }
+    };
+    // Listen for cross-tab changes via localStorage
+    const handleStorage = (event) => {
+        if (event.key === STORAGE_KEY) {
+            const value = event.newValue;
+            if (value === 'dark' || value === 'light') {
+                callback(value);
+            }
+            else {
+                // Key was removed — fall back to system preference
+                callback(getTheme());
+            }
+        }
+    };
+    // Listen for system preference changes
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const handleMedia = (event) => {
+        // Only fire if there is no explicit override in localStorage
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (!stored) {
+            callback(event.matches ? 'dark' : 'light');
+        }
+    };
+    window.addEventListener(THEME_CHANGE_EVENT, handleCustom);
+    window.addEventListener('storage', handleStorage);
+    mediaQuery.addEventListener('change', handleMedia);
+    return () => {
+        window.removeEventListener(THEME_CHANGE_EVENT, handleCustom);
+        window.removeEventListener('storage', handleStorage);
+        mediaQuery.removeEventListener('change', handleMedia);
+    };
+}

package/dist/src/dashboard/chart_aggregator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chart_aggregator.d.ts","sourceRoot":"","sources":["../../../src/dashboard/chart_aggregator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,KAAK,CAA8C;gBAE/C,EAAE,EAAE,IAAI;IAIpB,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;YAOE,SAAS;CA0DxB"}
+{"version":3,"file":"chart_aggregator.d.ts","sourceRoot":"","sources":["../../../src/dashboard/chart_aggregator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,KAAK,CAA8C;gBAE/C,EAAE,EAAE,IAAI;IAIpB,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;YAOE,SAAS;CA6DxB"}