@next-rsc-debug/core 0.1.3

package/README.md

@@ -0,0 +1,38 @@
+# @next-rsc-debug/core
+
+Framework-independent event protocol and collector for Next RSC Debug.
+
+## Features
+
+- DebugEvent types and factories
+- Event IDs, timestamps, and metadata
+- In-memory ring buffer (default 5000 events)
+- Event subscription support
+- URL sanitization utilities
+- Analyzer primitives (slow request, duplicate request, error detection)
+- Warning detection
+
+## Installation
+
+```bash
+pnpm add @next-rsc-debug/core
+```
+
+## Usage
+
+```ts
+import { createEvent, getCollector, analyzeEvents } from "@next-rsc-debug/core";
+
+const event = createEvent({
+  type: "fetch:start",
+  metadata: { url: "/api/foo" },
+});
+getCollector().push(event);
+
+const events = getCollector().list();
+const { warnings } = analyzeEvents(events);
+```
+
+## License
+
+MIT

package/dist/analyzer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Analyzer primitives: warning detection.
+ *
+ * Warnings:
+ * - slow-request: duration >= threshold (default 500ms)
+ * - duplicate-request: normalized URL groups
+ * - error: error events
+ */
+import type { DebugEvent, DebugEventType } from "./events.js";
+export type WarningSeverity = "info" | "warning";
+export type WarningType = "slow-request" | "duplicate-request" | "error";
+export interface Warning {
+    id: string;
+    type: WarningType;
+    severity: WarningSeverity;
+    eventIds: string[];
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface AnalyzeOptions {
+    slowThreshold?: number;
+}
+export declare function analyzeEvents(events: DebugEvent[], options?: AnalyzeOptions): {
+    warnings: Warning[];
+};
+export declare function normalizeFetchUrl(event: DebugEvent): string | undefined;
+export declare function isFetchEventType(type: DebugEventType): boolean;
+export declare function isNavigationEventType(type: DebugEventType): boolean;
+export declare function isRscEventType(type: DebugEventType): boolean;
+export declare function isCacheEventType(type: DebugEventType): boolean;
+export declare function isActionEventType(type: DebugEventType): boolean;
+export declare function isErrorEventType(type: DebugEventType): boolean;
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG9D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;AAEjD,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,mBAAmB,GAAG,OAAO,CAAC;AAEzE,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,cAAmB,GAC3B;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;CAAE,CA0EzB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAKvE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE9D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAEnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAI9D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE9D"}

package/dist/analyzer.js

@@ -0,0 +1,105 @@
+/**
+ * Analyzer primitives: warning detection.
+ *
+ * Warnings:
+ * - slow-request: duration >= threshold (default 500ms)
+ * - duplicate-request: normalized URL groups
+ * - error: error events
+ */
+import { sanitizeUrl } from "./sanitize.js";
+const DEFAULT_SLOW_THRESHOLD = 500;
+export function analyzeEvents(events, options = {}) {
+    const slowThreshold = options.slowThreshold ?? DEFAULT_SLOW_THRESHOLD;
+    const warnings = [];
+    // Slow request detection: events with duration >= threshold.
+    for (const event of events) {
+        if (event.duration !== undefined && event.duration >= slowThreshold) {
+            warnings.push({
+                id: `warn_slow_${event.id}`,
+                type: "slow-request",
+                severity: "warning",
+                eventIds: [event.id],
+                message: `Slow operation detected: ${event.duration}ms (threshold: ${slowThreshold}ms)`,
+                details: {
+                    duration: event.duration,
+                    threshold: slowThreshold,
+                    type: event.type,
+                    requestId: event.requestId,
+                },
+            });
+        }
+    }
+    // Duplicate detection: group fetch events by normalized URL.
+    const fetchGroups = new Map();
+    for (const event of events) {
+        if (event.type === "fetch:end" && event.metadata?.url) {
+            const url = sanitizeUrl(String(event.metadata.url));
+            const group = fetchGroups.get(url);
+            if (group) {
+                group.push(event);
+            }
+            else {
+                fetchGroups.set(url, [event]);
+            }
+        }
+    }
+    for (const [url, group] of fetchGroups) {
+        if (group.length > 1) {
+            warnings.push({
+                id: `warn_dup_${url.replace(/[^a-zA-Z0-9]/g, "_")}`,
+                type: "duplicate-request",
+                severity: "warning",
+                eventIds: group.map((e) => e.id),
+                message: `Duplicate request detected: ${url} (${group.length} times)`,
+                details: {
+                    url,
+                    count: group.length,
+                    requestIds: group
+                        .map((e) => e.requestId)
+                        .filter((id) => id !== undefined),
+                },
+            });
+        }
+    }
+    // Error detection.
+    for (const event of events) {
+        if (event.type === "error") {
+            warnings.push({
+                id: `warn_error_${event.id}`,
+                type: "error",
+                severity: "warning",
+                eventIds: [event.id],
+                message: String(event.metadata?.message ?? "Unknown error"),
+                details: {
+                    requestId: event.requestId,
+                    metadata: event.metadata,
+                },
+            });
+        }
+    }
+    return { warnings };
+}
+export function normalizeFetchUrl(event) {
+    if (event.type !== "fetch:end" || !event.metadata?.url) {
+        return undefined;
+    }
+    return sanitizeUrl(String(event.metadata.url));
+}
+export function isFetchEventType(type) {
+    return type === "fetch:start" || type === "fetch:end";
+}
+export function isNavigationEventType(type) {
+    return type === "navigation:start" || type === "navigation:end";
+}
+export function isRscEventType(type) {
+    return type === "rsc:start" || type === "rsc:end";
+}
+export function isCacheEventType(type) {
+    return (type === "cache:hit" || type === "cache:miss" || type === "cache:invalidate");
+}
+export function isActionEventType(type) {
+    return type === "action:start" || type === "action:end";
+}
+export function isErrorEventType(type) {
+    return type === "error";
+}

package/dist/collector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Event collector: singleton ring buffer with subscription support.
+ *
+ * This is the central store used by the Next.js integration and DevTools UI.
+ *
+ * The instance is stored on `globalThis` rather than in module scope. Next.js
+ * bundles each route separately on the server, so a module-level variable
+ * would be duplicated per route chunk: events recorded while rendering a
+ * Server Component would land in a different collector than the one the
+ * debug-events route reads. Keying off `globalThis` gives every route chunk
+ * a single shared collector.
+ */
+import { type EventListener, type Unsubscribe } from "./ring-buffer.js";
+import type { DebugEvent } from "./events.js";
+export interface Collector {
+    push(event: DebugEvent): void;
+    list(): DebugEvent[];
+    listRange(start: number, end: number): DebugEvent[];
+    clear(): void;
+    size(): number;
+    capacity(): number;
+    subscribe(listener: EventListener): Unsubscribe;
+    destroy(): void;
+}
+export declare function getCollector(): Collector;
+export declare function createCollector(max?: number): Collector;
+export declare function setCollector(collector: Collector): void;
+export declare function resetCollector(): void;
+//# sourceMappingURL=collector.d.ts.map

package/dist/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,IAAI,IAAI,UAAU,EAAE,CAAC;IACrB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC;IACpD,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,MAAM,CAAC;IACf,QAAQ,IAAI,MAAM,CAAC;IACnB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW,CAAC;IAChD,OAAO,IAAI,IAAI,CAAC;CACjB;AAoDD,wBAAgB,YAAY,IAAI,SAAS,CAMxC;AAED,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAEvD;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAEvD;AAED,wBAAgB,cAAc,IAAI,IAAI,CAMrC"}

package/dist/collector.js

@@ -0,0 +1,67 @@
+/**
+ * Event collector: singleton ring buffer with subscription support.
+ *
+ * This is the central store used by the Next.js integration and DevTools UI.
+ *
+ * The instance is stored on `globalThis` rather than in module scope. Next.js
+ * bundles each route separately on the server, so a module-level variable
+ * would be duplicated per route chunk: events recorded while rendering a
+ * Server Component would land in a different collector than the one the
+ * debug-events route reads. Keying off `globalThis` gives every route chunk
+ * a single shared collector.
+ */
+import { RingBuffer, } from "./ring-buffer.js";
+class MemoryCollector {
+    buffer;
+    constructor(max) {
+        this.buffer = new RingBuffer({ max });
+    }
+    push(event) {
+        this.buffer.push(event);
+    }
+    list() {
+        return this.buffer.list();
+    }
+    listRange(start, end) {
+        return this.buffer.listRange(start, end);
+    }
+    clear() {
+        this.buffer.clear();
+    }
+    size() {
+        return this.buffer.size;
+    }
+    capacity() {
+        return this.buffer.capacity;
+    }
+    subscribe(listener) {
+        return this.buffer.subscribe(listener);
+    }
+    destroy() {
+        this.buffer.destroy();
+    }
+}
+const COLLECTOR_KEY = Symbol.for("next-rsc-debug.collector");
+function collectorGlobal() {
+    return globalThis;
+}
+export function getCollector() {
+    const store = collectorGlobal();
+    if (!store[COLLECTOR_KEY]) {
+        store[COLLECTOR_KEY] = new MemoryCollector();
+    }
+    return store[COLLECTOR_KEY];
+}
+export function createCollector(max) {
+    return new MemoryCollector(max);
+}
+export function setCollector(collector) {
+    collectorGlobal()[COLLECTOR_KEY] = collector;
+}
+export function resetCollector() {
+    const store = collectorGlobal();
+    if (store[COLLECTOR_KEY]) {
+        store[COLLECTOR_KEY].destroy();
+        store[COLLECTOR_KEY] = undefined;
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DebugEvent types and factories for Next RSC Debug.
+ *
+ * Every event has a unique ID, timestamp, and type.
+ * Optional fields: duration, requestId, parentId, metadata.
+ */
+export type DebugEventType = "navigation:start" | "navigation:end" | "rsc:start" | "rsc:end" | "fetch:start" | "fetch:end" | "cache:hit" | "cache:miss" | "cache:invalidate" | "action:start" | "action:end" | "error";
+export interface DebugEvent {
+    id: string;
+    type: DebugEventType;
+    timestamp: number;
+    duration?: number;
+    requestId?: string;
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateEventOptions {
+    type: DebugEventType;
+    requestId?: string;
+    parentId?: string;
+    duration?: number;
+    metadata?: Record<string, unknown>;
+}
+export declare function createRequestId(): string;
+export declare function createNavigationId(): string;
+export declare function createEventId(prefix: string): string;
+export declare function createEvent(options: CreateEventOptions): DebugEvent;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,gBAAgB,GAChB,WAAW,GACX,SAAS,GACT,aAAa,GACb,WAAW,GACX,WAAW,GACX,YAAY,GACZ,kBAAkB,GAClB,cAAc,GACd,YAAY,GACZ,OAAO,CAAC;AAEZ,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAkBD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU,CAmBnE"}

package/dist/events.js

@@ -0,0 +1,50 @@
+/**
+ * DebugEvent types and factories for Next RSC Debug.
+ *
+ * Every event has a unique ID, timestamp, and type.
+ * Optional fields: duration, requestId, parentId, metadata.
+ */
+let idCounter = 0;
+let lastTimestamp = 0;
+function generateId(prefix) {
+    // Use a combination of timestamp, counter, and random for uniqueness.
+    const now = Date.now();
+    if (now === lastTimestamp) {
+        idCounter += 1;
+    }
+    else {
+        idCounter = 0;
+        lastTimestamp = now;
+    }
+    const random = Math.floor(Math.random() * 1_000_000);
+    return `${prefix}_${now}_${idCounter}_${random}`;
+}
+export function createRequestId() {
+    return generateId("req");
+}
+export function createNavigationId() {
+    return generateId("nav");
+}
+export function createEventId(prefix) {
+    return generateId(prefix);
+}
+export function createEvent(options) {
+    const event = {
+        id: generateId(options.type.replace(/:/g, "_")),
+        type: options.type,
+        timestamp: Date.now(),
+    };
+    if (options.requestId !== undefined) {
+        event.requestId = options.requestId;
+    }
+    if (options.parentId !== undefined) {
+        event.parentId = options.parentId;
+    }
+    if (options.duration !== undefined) {
+        event.duration = options.duration;
+    }
+    if (options.metadata !== undefined) {
+        event.metadata = options.metadata;
+    }
+    return event;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public API for @next-rsc-debug/core.
+ */
+export { createEvent, createEventId, createRequestId, createNavigationId, type DebugEvent, type DebugEventType, type CreateEventOptions, } from "./events.js";
+export { sanitizeUrl, stripSensitiveQueryParams, isSafeKey, } from "./sanitize.js";
+export { RingBuffer, type EventListener, type Unsubscribe, type RingBufferOptions, } from "./ring-buffer.js";
+export { analyzeEvents, type Warning, type WarningType, type WarningSeverity, type AnalyzeOptions, normalizeFetchUrl, isFetchEventType, isNavigationEventType, isRscEventType, isCacheEventType, isActionEventType, isErrorEventType, } from "./analyzer.js";
+export { getCollector, createCollector, setCollector, resetCollector, type Collector, } from "./collector.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,yBAAyB,EACzB,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,UAAU,EACV,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,KAAK,SAAS,GACf,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * Public API for @next-rsc-debug/core.
+ */
+export { createEvent, createEventId, createRequestId, createNavigationId, } from "./events.js";
+export { sanitizeUrl, stripSensitiveQueryParams, isSafeKey, } from "./sanitize.js";
+export { RingBuffer, } from "./ring-buffer.js";
+export { analyzeEvents, normalizeFetchUrl, isFetchEventType, isNavigationEventType, isRscEventType, isCacheEventType, isActionEventType, isErrorEventType, } from "./analyzer.js";
+export { getCollector, createCollector, setCollector, resetCollector, } from "./collector.js";

package/dist/ring-buffer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * In-memory ring buffer for events.
+ *
+ * Requirements:
+ * - Configurable max event count (default 5000).
+ * - FIFO eviction.
+ * - list(), clear(), push().
+ * - Subscription support.
+ * - Safe concurrent usage in Node.js.
+ * - No memory leaks.
+ */
+import type { DebugEvent } from "./events.js";
+export type EventListener = (event: DebugEvent) => void;
+export type Unsubscribe = () => void;
+export interface RingBufferOptions {
+    max?: number;
+}
+export declare class RingBuffer {
+    private readonly max;
+    private events;
+    private listeners;
+    constructor(options?: RingBufferOptions);
+    push(event: DebugEvent): void;
+    list(): DebugEvent[];
+    listRange(start: number, end: number): DebugEvent[];
+    clear(): void;
+    get size(): number;
+    get capacity(): number;
+    subscribe(listener: EventListener): Unsubscribe;
+    get listenerCount(): number;
+    destroy(): void;
+}
+//# sourceMappingURL=ring-buffer.d.ts.map

package/dist/ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../src/ring-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAuB;gBAE5B,OAAO,GAAE,iBAAsB;IAO3C,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAgB7B,IAAI,IAAI,UAAU,EAAE;IAIpB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE;IAOnD,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW;IAU/C,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,OAAO,IAAI,IAAI;CAIhB"}

package/dist/ring-buffer.js

@@ -0,0 +1,73 @@
+/**
+ * In-memory ring buffer for events.
+ *
+ * Requirements:
+ * - Configurable max event count (default 5000).
+ * - FIFO eviction.
+ * - list(), clear(), push().
+ * - Subscription support.
+ * - Safe concurrent usage in Node.js.
+ * - No memory leaks.
+ */
+const DEFAULT_MAX = 5000;
+export class RingBuffer {
+    max;
+    events = [];
+    listeners = [];
+    constructor(options = {}) {
+        this.max = options.max ?? DEFAULT_MAX;
+        if (!Number.isFinite(this.max) || this.max <= 0) {
+            throw new Error("RingBuffer max must be a positive number");
+        }
+    }
+    push(event) {
+        this.events.push(event);
+        if (this.events.length > this.max) {
+            this.events.shift();
+        }
+        // Notify listeners (synchronous, bounded).
+        for (let i = 0; i < this.listeners.length; i++) {
+            const listener = this.listeners[i];
+            try {
+                listener(event);
+            }
+            catch {
+                // Never let a listener crash the collector.
+            }
+        }
+    }
+    list() {
+        return this.events.slice();
+    }
+    listRange(start, end) {
+        const len = this.events.length;
+        const from = Math.max(0, Math.min(start, len));
+        const to = Math.max(0, Math.min(end, len));
+        return this.events.slice(from, to);
+    }
+    clear() {
+        this.events = [];
+    }
+    get size() {
+        return this.events.length;
+    }
+    get capacity() {
+        return this.max;
+    }
+    subscribe(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const index = this.listeners.indexOf(listener);
+            if (index !== -1) {
+                this.listeners.splice(index, 1);
+            }
+        };
+    }
+    get listenerCount() {
+        return this.listeners.length;
+    }
+    destroy() {
+        this.events = [];
+        this.listeners = [];
+    }
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sanitization utilities for URLs and metadata.
+ *
+ * Rules:
+ * - Strip query strings by default.
+ * - Strip credentials embedded in URLs.
+ * - Never store cookies, auth headers, request bodies, response bodies,
+ *   passwords, or tokens.
+ */
+export declare function sanitizeUrl(url: string): string;
+export declare function stripSensitiveQueryParams(url: string): string;
+export declare function isSafeKey(key: string): boolean;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyB/C;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA+B7D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM9C"}

package/dist/sanitize.js

@@ -0,0 +1,88 @@
+/**
+ * Sanitization utilities for URLs and metadata.
+ *
+ * Rules:
+ * - Strip query strings by default.
+ * - Strip credentials embedded in URLs.
+ * - Never store cookies, auth headers, request bodies, response bodies,
+ *   passwords, or tokens.
+ */
+const SENSITIVE_QUERY_PARAMS = new Set([
+    "token",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "api_key",
+    "apikey",
+    "secret",
+    "password",
+    "passwd",
+    "pwd",
+    "auth",
+    "authorization",
+    "session",
+    "sessionid",
+    "cookie",
+    "csrf",
+    "xsrf",
+    "private_key",
+    "client_secret",
+]);
+export function sanitizeUrl(url) {
+    if (typeof url !== "string" || url.length === 0) {
+        return "";
+    }
+    let sanitized;
+    try {
+        const parsed = new URL(url);
+        // Strip the query string entirely.
+        parsed.search = "";
+        // Strip the hash fragment.
+        parsed.hash = "";
+        sanitized = parsed.toString();
+    }
+    catch {
+        // If the URL cannot be parsed, strip anything that looks like a query string.
+        sanitized = url.split("?")[0].split("#")[0];
+    }
+    // Also strip credentials embedded in the URL (user:pass@host).
+    sanitized = sanitized.replace(/^(https?:\/\/)[^:/@\s]+:[^@/\s]+@/, "$1");
+    // Remove userinfo entirely if present (user@host without password).
+    sanitized = sanitized.replace(/^(https?:\/\/)[^@/\s]+@/, "$1");
+    return sanitized;
+}
+export function stripSensitiveQueryParams(url) {
+    if (typeof url !== "string" || url.length === 0) {
+        return "";
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url.split("#")[0];
+    }
+    const params = parsed.searchParams;
+    const sensitiveKeys = [];
+    for (const key of params.keys()) {
+        if (SENSITIVE_QUERY_PARAMS.has(key.toLowerCase())) {
+            sensitiveKeys.push(key);
+        }
+    }
+    if (sensitiveKeys.length === 0) {
+        return url.split("#")[0];
+    }
+    for (const key of sensitiveKeys) {
+        params.delete(key);
+    }
+    parsed.search = params.toString();
+    parsed.hash = "";
+    return parsed.toString();
+}
+export function isSafeKey(key) {
+    if (typeof key !== "string") {
+        return false;
+    }
+    const lower = key.toLowerCase();
+    return !SENSITIVE_QUERY_PARAMS.has(lower);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@next-rsc-debug/core",
+  "version": "0.1.3",
+  "description": "Framework-independent event protocol and collector for Next RSC Debug",
+  "author": "Samith Mendis",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --config vitest.config.ts",
+    "lint": "eslint src --ext .ts"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}