sibujs 1.2.0 → 1.4.0

package/dist/devtools.d.ts

@@ -1,477 +1,85 @@
-import { R as ReactiveSignal } from './signal-BnWpq6WB.js';
+export { D as DevToolsEvent, a as DevtoolsOverlayOptions, P as ProfilerResult, R as ReactiveNodeInfo, S as SibuError, c as checkLeaks, b as clearDebugValues, d as clearHMRState, e as clearPerformanceData, f as createDevtoolsOverlay, g as createErrorReporter, h as createHMRBoundary, i as createProfiler, j as debugLog, k as debugValue, l as devState, m as disableDebug, n as enableDebug, o as formatError, p as getActiveDevTools, q as getDebugValues, r as getDependencies, s as getPerformanceReport, t as getSignalName, u as getSubscriberCount, v as hmrState, w as initDevTools, x as inspectSignal, y as isDebugEnabled, z as isHMRAvailable, A as measureRender, B as perfTracker, C as registerHMR, E as runCleanups, F as startMeasure, G as trackCleanup, H as walkDependencyGraph, I as withErrorTracking } from './introspect-CZrlcaYy.js';
+import './signal-BnWpq6WB.js';
 
-/**
- * Enable debug mode — enables verbose logging.
- */
-declare function enableDebug(): void;
-/**
- * Disable debug mode.
- */
-declare function disableDebug(): void;
-/**
- * Check if debug mode is active.
- */
-declare function isDebugEnabled(): boolean;
-/**
- * Log a debug message (only when debug mode is enabled).
- */
-declare function debugLog(component: string, action: string, data?: unknown): void;
-/**
- * perfTracker tracks render timing for a component.
- */
-declare function perfTracker(label: string): {
-    startMeasure: () => void;
-    endMeasure: () => number;
-    getAverageTime: () => number;
-    getRenderCount: () => number;
-};
-/**
- * measureRender wraps a component and measures its render time.
- */
-declare function measureRender<P>(label: string, component: (props: P) => HTMLElement): (props: P) => HTMLElement;
-/**
- * Get all collected performance data.
- */
-declare function getPerformanceReport(): Record<string, {
-    count: number;
-    average: number;
-    min: number;
-    max: number;
-    total: number;
-}>;
-/**
- * Clear all performance data.
- */
-declare function clearPerformanceData(): void;
-declare function trackCleanup(component: string, cleanup: () => void): void;
-declare function runCleanups(component: string): void;
-declare function checkLeaks(): Record<string, number>;
-
-/**
- * Sibu DevTools Bridge
- *
- * Architecture (React DevTools style):
- *
- *   Sibu App                    Chrome Extension
- *   ┌──────────┐               ┌──────────────┐
- *   │ signal  │──emit──▶│    │  Content      │
- *   │ derived │        │    │  Script       │
- *   │ effect  │        ▼    │   │            │
- *   │ mount     │   __SIBU_   │   ▼            │
- *   └──────────┘   DEVTOOLS_  │  Background   │
- *                  GLOBAL_    │   │            │
- *                  HOOK__     │   ▼            │
- *                    │        │  DevTools      │
- *                    │        │  Panel         │
- *                    ▼        └──────────────┘
- *                 Bridge
- *              (postMessage)
- *
- * The hook is injected by the content script BEFORE the app loads.
- * When initDevTools() is called, the bridge connects to the existing hook
- * or creates one. Events are buffered until the panel connects.
- */
-type DevToolsEvent = {
-    type: "state-change";
-    component: string;
-    key: string;
-    oldValue: unknown;
-    newValue: unknown;
-    timestamp: number;
-} | {
-    type: "mount";
-    component: string;
-    element: HTMLElement;
-    timestamp: number;
-} | {
-    type: "unmount";
-    component: string;
-    timestamp: number;
-} | {
-    type: "render";
-    component: string;
-    duration: number;
-    timestamp: number;
-} | {
-    type: "error";
-    component: string;
-    error: Error;
-    timestamp: number;
-};
-interface DevToolsConfig {
-    maxEvents?: number;
-    enabled?: boolean;
-    maxSignals?: number;
+interface SignalNodeSnapshot {
+    /** Stable id for the node (assigned on first observation). */
+    id: string;
+    /** Debug name, if the caller tagged the signal. */
+    name: string | null;
+    /** Runtime type tag: `"signal"`, `"derived"`, `"effect"`. */
+    kind: string;
+    /** Best-effort preview of the current value. */
+    value: string;
+    /** Ids of nodes that depend on this one. */
+    subscribers: string[];
+    /** Ids of nodes this one reads from. */
+    dependencies: string[];
+    /** Number of times the node has been re-evaluated since creation. */
+    evalCount: number;
 }
-interface ComponentEntry {
-    element: HTMLElement;
-    state?: Record<string, unknown>;
+interface SignalGraphSnapshot {
+    capturedAt: number;
+    nodes: SignalNodeSnapshot[];
+    /** Total edge count for quick health checks. */
+    edgeCount: number;
 }
-declare function getActiveDevTools(): ReturnType<typeof initDevTools> | null;
-/**
- * Initialize Sibu DevTools.
- * Connects to __SIBU_DEVTOOLS_GLOBAL_HOOK__ and starts tracking signals,
- * computed values, effects, and components.
- */
-declare function initDevTools(config?: DevToolsConfig): {
-    record: (event: DevToolsEvent) => void;
-    getEvents: (filter?: {
-        type?: string;
-        component?: string;
-    }) => DevToolsEvent[];
-    clearEvents: () => void;
-    registerComponent: (name: string, element: HTMLElement, state?: Record<string, unknown>) => void;
-    unregisterComponent: (name: string) => void;
-    getComponents: () => Map<string, ComponentEntry>;
-    getSignals: () => Array<{
-        id: number;
-        name: string;
-        type: string;
-        value: unknown;
-        subscriberCount: number;
-    }>;
-    isEnabled: () => boolean;
-    setEnabled: (v: boolean) => void;
-    snapshot: () => Record<string, unknown>;
-    highlightElement: (name: string) => void;
-    destroy: () => void;
-};
-declare function devState<T>(name: string, initial: T): [() => T, (value: T | ((prev: T) => T)) => void];
-
-/**
- * Hot Module Replacement utilities for SibuJS.
- * Preserves component state during development reloads.
- *
- * During development the HMR runtime keeps a global store of component state
- * keyed by a developer-supplied ID.  When a module is hot-reloaded the new
- * component implementation can re-use the preserved state so that the user
- * does not lose context (form values, scroll position, etc.).
- *
- * The utilities integrate with bundlers that expose a `module.hot` or
- * `import.meta.hot` API (Webpack, Vite, Parcel, etc.).
- */
-/**
- * Create an HMR-aware state that persists across module reloads.
- * During development, state is stored in a global map keyed by a unique `id`.
- * On the first load the `initial` value is used; on subsequent hot reloads
- * the previously stored value is restored.
- *
- * @param id       Unique identifier for this state (should be stable across reloads)
- * @param initial  Initial value used on the very first load
- * @returns A `[getter, setter]` tuple compatible with `signal`
- *
- * @example
- * ```ts
- * const [count, setCount] = hmrState("MyCounter.count", 0);
- * // After a hot reload, `count()` will still return the last known value.
- * ```
- */
-declare function hmrState<T>(id: string, initial: T): [() => T, (value: T | ((prev: T) => T)) => void];
-/**
- * Register a component for HMR updates.
- * When the module is hot-reloaded the component is re-rendered with preserved
- * state by swapping out the old DOM element for the new one produced by the
- * updated component function.
- *
- * @param id          Stable identifier for the component
- * @param component   Factory function that returns the component's root element
- * @param container   Optional container element – if provided the initial element
- *                    is automatically appended to it
- * @returns An object with `update` (swap implementation) and `dispose` (clean up)
- *
- * @example
- * ```ts
- * const hmr = registerHMR("MyWidget", () => MyWidget());
- *
- * // On hot update:
- * hmr.update(() => MyWidgetV2());
- *
- * // On full teardown:
- * hmr.dispose();
- * ```
- */
-declare function registerHMR(id: string, component: () => HTMLElement, container?: HTMLElement): {
-    /** Update the component implementation (called on hot reload) */
-    update: (newComponent: () => HTMLElement) => void;
-    /** Dispose the HMR registration */
-    dispose: () => void;
-};
-/**
- * Create an HMR boundary.
- * Components within the boundary are hot-reloaded independently.  The boundary
- * keeps track of accept/dispose callbacks and can wrap a component factory so
- * that hot updates are handled transparently.
- *
- * @param id  Stable boundary identifier
- * @returns Boundary helpers: `wrap`, `accept`, `dispose`
- *
- * @example
- * ```ts
- * const boundary = createHMRBoundary("settings-panel");
- *
- * const el = boundary.wrap(() => SettingsPanel());
- * document.body.appendChild(el);
- *
- * boundary.accept(() => console.log("Hot update accepted"));
- * boundary.dispose(() => console.log("Cleaning up old version"));
- * ```
- */
-declare function createHMRBoundary(id: string): {
-    /** Wrap a component for HMR support */
-    wrap: (component: () => HTMLElement) => HTMLElement;
-    /** Accept a hot update */
-    accept: (callback?: () => void) => void;
-    /** Dispose callback */
-    dispose: (callback: () => void) => void;
-};
-/**
- * Clear all HMR state (useful for a full page refresh or test teardown).
- */
-declare function clearHMRState(): void;
-/**
- * Check if HMR is available in the current environment.
- * Returns `true` when any of the common bundler HMR APIs are detected
- * (`module.hot` for Webpack, `import.meta.hot` for Vite, or the SibuJS
- * custom hook).
- */
-declare function isHMRAvailable(): boolean;
-
 /**
- * Source map and debugging utilities for SibuJS.
- * Provides enhanced error reporting with component context and stack traces.
+ * Capture a synchronous snapshot of the reactive graph. The hook
+ * provides a `getSignalNodes()` iterator that the core reactivity
+ * layer populates; this function walks it and produces a serializable
+ * view with dependency counts.
  *
- * These utilities do not parse `.map` files at runtime; instead they enrich
- * errors with SibuJS-specific component context so that developers can quickly
- * identify *which* component failed and *what* props were in play, regardless
- * of whether source maps are available in the browser.
+ * Returns an empty snapshot when devtools are not enabled.
  */
+declare function captureSignalGraph(): SignalGraphSnapshot;
 /**
- * Enhanced error class with component context.
- *
- * Extends the native `Error` to carry the component name and the props that
- * were active when the error was thrown.  The `cause` property (ES2022) is
- * also forwarded so that the original error is preserved.
- *
- * @example
- * ```ts
- * throw new SibuError("Render failed", {
- *   component: "UserCard",
- *   props: { userId: 42 },
- *   cause: originalError,
- * });
- * ```
- */
-declare class SibuError extends Error {
-    component?: string;
-    props?: Record<string, unknown>;
-    constructor(message: string, options?: {
-        component?: string;
-        props?: Record<string, unknown>;
-        cause?: Error;
-    });
-}
-/**
- * Create a component error reporter that captures stack traces and maps them
- * to component context.
- *
- * The reporter collects errors into an internal list, optionally logs them
- * to the console, and forwards them to a user-supplied `onError` handler.
- *
- * @param options Configuration options
- * @returns Reporter API
- *
- * @example
- * ```ts
- * const reporter = createErrorReporter({
- *   onError: (err) => analytics.track("component_error", err),
- *   logToConsole: true,
- *   maxErrors: 200,
- * });
- *
- * reporter.report(new Error("oops"), { component: "Dashboard" });
- * console.log(reporter.getErrors());
- * ```
+ * Diff two snapshots and return a high-level summary: how many new
+ * nodes, how many removed, and which nodes re-evaluated between
+ * captures. Useful for regression tests that want to assert
+ * "navigating to /page X creates exactly N new signals".
  */
-declare function createErrorReporter(options?: {
-    /** Custom error handler */
-    onError?: (error: SibuError) => void;
-    /** Whether to log to console (default `true`) */
-    logToConsole?: boolean;
-    /** Max errors to retain */
-    maxErrors?: number;
-}): {
-    /** Report an error with component context */
-    report: (error: Error, context?: {
-        component?: string;
-        props?: Record<string, unknown>;
-    }) => void;
-    /** Get all reported errors */
-    getErrors: () => SibuError[];
-    /** Clear error history */
-    clear: () => void;
-    /** Get error count by component */
-    getErrorsByComponent: () => Map<string, SibuError[]>;
+declare function diffSignalGraphs(before: SignalGraphSnapshot, after: SignalGraphSnapshot): {
+    added: SignalNodeSnapshot[];
+    removed: SignalNodeSnapshot[];
+    reevaluated: SignalNodeSnapshot[];
 };
-/**
- * Wrap a component factory with error tracking.
- * Catches errors during rendering and reports them via the supplied reporter
- * (or a default one).  If the component throws, a fallback `<div>` with the
- * error message is returned so the rest of the page is not broken.
- *
- * @param name       Human-readable component name
- * @param component  Factory function that returns an `HTMLElement`
- * @param reporter   Optional error reporter (a default is created if omitted)
- * @returns A wrapped factory function with identical signature
- *
- * @example
- * ```ts
- * const SafeWidget = withErrorTracking("Widget", () => Widget(), reporter);
- * document.body.appendChild(SafeWidget());
- * ```
- */
-declare function withErrorTracking(name: string, component: () => HTMLElement, reporter?: ReturnType<typeof createErrorReporter>): () => HTMLElement;
-/**
- * Format an error with enhanced stack trace information.
- * Adds component context markers to stack traces so that the developer can
- * immediately see which SibuJS component is involved.
- *
- * @param error    The error to format
- * @param context  Optional context to include in the formatted output
- * @returns A formatted multi-line string suitable for `console.error`
- *
- * @example
- * ```ts
- * try {
- *   render();
- * } catch (e) {
- *   console.error(formatError(e, { component: "App" }));
- * }
- * ```
- */
-declare function formatError(error: Error, context?: {
-    component?: string;
-}): string;
-
-/**
- * Registers a reactive value for DevTools inspection.
- * Uses an effect internally to track changes — the formatter is called
- * on every update, and the latest snapshot is stored for DevTools.
- *
- * @param value Reactive getter (e.g., a signal)
- * @param formatter Optional function to convert value to a display label
- * @returns Dispose function to stop tracking
- */
-declare function debugValue<T>(value: () => T, formatter?: (value: T) => string): () => void;
-/**
- * Returns all currently registered debug values.
- */
-declare function getDebugValues(): Array<{
-    value: unknown;
-    label: string;
-}>;
-/**
- * Clears all registered debug values.
- */
-declare function clearDebugValues(): void;
-
-interface ProfilerResult {
-    renderCount: () => number;
-    lastRenderTime: () => number;
-    averageRenderTime: () => number;
-    totalRenderTime: () => number;
-    reset: () => void;
-}
-/**
- * Creates a component profiler that tracks render counts and timings.
- * Uses performance.now() for high-resolution timing.
- * All outputs are reactive via signal.
- */
-declare function createProfiler(_name: string): ProfilerResult;
-/**
- * Starts a render measurement for the given profiler.
- * Returns a stop function that records the elapsed time.
- */
-declare function startMeasure(profiler: ProfilerResult): () => void;
-
-interface DevtoolsOverlayOptions {
-    enabled?: boolean;
-    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+interface ProfilerEvent {
+    /** Chrome tracing `name` field — effect/signal label. */
+    name: string;
+    /** Trace category. */
+    cat: string;
+    /** `"B"` = begin, `"E"` = end, `"I"` = instant. */
+    ph: "B" | "E" | "I";
+    /** Timestamp in microseconds since the profiler started. */
+    ts: number;
+    /** Fixed thread ID — sibujs has one reactive thread. */
+    tid: 0;
+    /** Fixed process ID. */
+    pid: 0;
+    /** Arbitrary metadata. */
+    args?: Record<string, unknown>;
 }
-/**
- * Creates an in-browser devtools overlay manager.
- * Manages panels and visibility state reactively.
- * Does NOT create actual DOM elements — that's the consumer's job.
- */
-declare function createDevtoolsOverlay(options?: DevtoolsOverlayOptions): {
-    isEnabled: () => boolean;
-    toggle: () => void;
-    addPanel: (name: string, render: () => string) => void;
-    removePanel: (name: string) => void;
-    getPanels: () => Array<{
-        name: string;
-        render: () => string;
-    }>;
-    dispose: () => void;
-};
-
-/**
- * DevTools introspection utilities for SibuJS.
- *
- * These functions allow dev tools to inspect the reactive dependency graph
- * at runtime. They are designed to be zero-cost when not used — no overhead
- * is added to the hot path. Information is read from tags already placed
- * on signals/getters by signal, derived, etc.
- */
-
-/** Info about a reactive node in the dependency graph */
-interface ReactiveNodeInfo {
-    /** Debug name if provided (e.g., signal(0, { name: "count" })) */
-    name: string | undefined;
-    /** Internal signal reference */
-    signal: ReactiveSignal;
-    /** Number of subscribers */
-    subscriberCount: number;
+interface TraceProfilerHandle {
+    /** Stop the profiler and return the collected events. */
+    stop: () => ProfilerEvent[];
+    /** Stop and return a Chrome tracing JSON blob ready for download. */
+    stopTrace: () => string;
+    /** Whether the profiler is currently recording. */
+    isRecording: () => boolean;
 }
 /**
- * Get the debug name of a signal getter function.
- * Returns undefined if no name was provided.
+ * Start recording reactive effect timings. Returns a handle whose
+ * `stop()` method yields a list of Chrome tracing events — drop the
+ * JSON into `chrome://tracing` or `ui.perfetto.dev` to see the
+ * flamegraph.
  *
- * @example
- * const [count] = signal(0, { name: "count" });
- * getSignalName(count); // "count"
- */
-declare function getSignalName(getter: () => unknown): string | undefined;
-/**
- * Get the number of active subscribers for a signal getter.
- *
- * @example
- * const [count] = signal(0);
- * effect(() => count()); // +1 subscriber
- * getSubscriberCount(count); // 1
- */
-declare function getSubscriberCount(getter: () => unknown): number;
-/**
- * Get the dependency list of an effect or computed subscriber function.
- * Returns signal references that the subscriber depends on.
+ * In production this is a no-op; the handle still returns an empty
+ * list so callers do not have to branch on `isDev()` themselves.
  *
- * Note: This reads the _deps Set that track.ts maintains on subscriber functions.
+ * Named `createTraceProfiler` to avoid colliding with the per-component
+ * render profiler in `componentProfiler.ts`, which tracks render counts
+ * rather than producing a trace file.
  */
-declare function getDependencies(subscriberFn: () => void): ReactiveSignal[];
-/**
- * Inspect a signal getter — returns name, signal ref, and subscriber count.
- */
-declare function inspectSignal(getter: () => unknown): ReactiveNodeInfo | null;
-/**
- * Walk the full reactive graph starting from a signal getter.
- * Returns a tree of signal → subscribers → their signals → etc.
- * Useful for devtools visualization.
- *
- * Set maxDepth to limit traversal (default: 10).
- */
-declare function walkDependencyGraph(getter: () => unknown, maxDepth?: number): {
-    name: string | undefined;
-    subscribers: number;
-    downstream: ReturnType<typeof walkDependencyGraph>[];
-};
+declare function createTraceProfiler(): TraceProfilerHandle;
 
-export { type DevToolsEvent, type DevtoolsOverlayOptions, type ProfilerResult, type ReactiveNodeInfo, SibuError, checkLeaks, clearDebugValues, clearHMRState, clearPerformanceData, createDevtoolsOverlay, createErrorReporter, createHMRBoundary, createProfiler, debugLog, debugValue, devState, disableDebug, enableDebug, formatError, getActiveDevTools, getDebugValues, getDependencies, getPerformanceReport, getSignalName, getSubscriberCount, hmrState, initDevTools, inspectSignal, isDebugEnabled, isHMRAvailable, measureRender, perfTracker, registerHMR, runCleanups, startMeasure, trackCleanup, walkDependencyGraph, withErrorTracking };
+export { type ProfilerEvent, type SignalGraphSnapshot, type SignalNodeSnapshot, type TraceProfilerHandle, captureSignalGraph, createTraceProfiler, diffSignalGraphs };