@omniaura/solid-pulse 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import { j as Rect, c as ComponentRef, g as PulseController, E as ElementRef, d as EventBus, e as Feature } from './controller-3akN6Qi0.js';
+export { a as CommandResult, C as CommandSpec, f as Filters, P as PulseEvent, i as PulseEventKind } from './controller-3akN6Qi0.js';
+
+/**
+ * Visual layer. One fixed, pointer-events:none container holds every flash
+ * rectangle and badge, so the overlay can never shift layout, take focus or
+ * intercept input. Everything is plain DOM (no Solid) so it produces no
+ * reactive events of its own and works with any Solid version.
+ */
+
+type FlashKind = "dom" | "mount" | "reattach" | "query" | "highlight";
+declare class FlashOverlay {
+    private root;
+    private live;
+    private badges;
+    private reduced;
+    mount(): void;
+    unmount(): void;
+    get mounted(): boolean;
+    /** Flash rectangles in viewport coordinates. Drops extras beyond the live cap. */
+    flash(rects: readonly Rect[], kind: FlashKind, opts?: {
+        ms?: number;
+        label?: string;
+    }): number;
+    /**
+     * Transient badge centred on `at` (or the viewport when null). Used for the
+     * Solid Query overlay: "<Component> observing ['todos', 1]".
+     */
+    badge(html: {
+        title: string;
+        body?: string;
+    }, at: Rect | null, opts?: {
+        ms?: number;
+        kind?: FlashKind;
+    }): boolean;
+}
+
+/**
+ * Solid instrumentation through the official dev hooks (`DEV.hooks`), which
+ * exist only in Solid's development build. In a production build `DEV` is
+ * undefined and this module becomes a no-op — nothing is patched.
+ *
+ * What we see, precisely:
+ *  - `afterCreateOwner(owner)` fires for every root, computation and (in dev)
+ *    every component: dev components are computations carrying `.component`.
+ *  - We wrap each non-component computation's `fn` so we know when a memo /
+ *    effect / render-effect actually re-runs. Solid never re-runs component
+ *    bodies, so there is no "rerender" to report — only these.
+ *  - `afterUpdate()` marks the end of a synchronous update; together with a
+ *    microtask fallback it closes a "flush" group used to attribute DOM
+ *    mutations to the computations that produced them.
+ *  - `sharedConfig.context` is set while hydrating, so mounts during hydration
+ *    are labelled as such.
+ */
+
+interface ComponentInfo {
+    id: number;
+    name: string;
+    parent: number | null;
+    hydrated: boolean;
+    mountedAt: number;
+    mountedWall: number;
+    flush: number;
+    disposedAt: number | null;
+}
+interface SolidInstrumentation {
+    readonly available: boolean;
+    flushId(): number;
+    /** Components whose computations ran in the most recently closed flush. */
+    lastFlushComponents(): ComponentRef[];
+    componentFor(owner: unknown): ComponentRef | null;
+    currentComponent(): ComponentRef | null;
+    components(): ComponentInfo[];
+    attachElement(componentId: number, el: Element): void;
+    rectFor(component: ComponentRef): Rect | null;
+    elementsFor(componentId: number): Element[];
+    dispose(): void;
+}
+
+/**
+ * Page-side bridge transport. Streams events to the bridge server in ≤50 ms
+ * batches and executes commands the server relays from the CLI/agents. Any
+ * command is just `controller.run(name, args)` — the same call the panel makes.
+ */
+
+interface BridgeClientOptions {
+    /** ws(s):// URL. Default: same origin + /__pulse/ws. */
+    url?: string;
+    /** Reconnect delay in ms (default 2000). */
+    reconnectMs?: number;
+    /** Stable client id (default: random per page load, persisted in sessionStorage). */
+    clientId?: string;
+}
+declare class BridgeClient {
+    private controller;
+    private options;
+    private ws;
+    private timer;
+    private queue;
+    private flushTimer;
+    private unsubscribe;
+    private closed;
+    private NativeWebSocket;
+    readonly url: string;
+    readonly clientId: string;
+    connected: boolean;
+    constructor(controller: PulseController, options?: BridgeClientOptions);
+    connect(): void;
+    disconnect(): void;
+    private scheduleFlush;
+    private flush;
+    private send;
+    private onMessage;
+}
+
+/**
+ * DOM observation. A MutationObserver tells us what actually changed on
+ * screen; nothing here infers "rerenders". Beyond plain mutations it detects
+ * the pattern that costs people days: a subtree is removed and the *same node
+ * instance* is re-inserted moments later (a Suspense boundary flipping to its
+ * fallback and back, a keyed <Show>/<Switch> toggling). That detach/reattach
+ * silently resets scroll positions to 0 and drops focus to <body>, with no
+ * component cleanup running — so we record scrollTop and focus at detach time
+ * and compare after reattach.
+ */
+
+declare function describeElement(el: Element, withRect?: boolean): ElementRef;
+declare function toSelector(el: Element): string;
+
+/**
+ * @omniaura/solid-pulse — runtime entry.
+ *
+ *   import { initPulse } from "@omniaura/solid-pulse";
+ *   if (import.meta.env.DEV) initPulse({ bridge: true });
+ *
+ * or let `@omniaura/solid-pulse/vite` auto-import it in dev. Never ship it in
+ * production: the Vite plugin is `apply: "serve"` and `initPulse` refuses to
+ * run twice. Instrumentation is dev-only and everything is bounded (ring
+ * buffer, per-frame flash caps, per-stream message caps).
+ */
+
+interface PulseOptions {
+    /** Ring-buffer capacity (default 2000 events). */
+    bufferSize?: number;
+    /** Initial feature flags. */
+    features?: Partial<Record<Feature, boolean>>;
+    /** Mount the flash/badge overlay (default true). */
+    overlay?: boolean;
+    /**
+     * Connect to a bridge. `true` uses the same origin at `/__pulse/ws` (the
+     * Vite plugin mounts one there); a string is an explicit ws:// URL.
+     */
+    bridge?: boolean | string | BridgeClientOptions;
+    /** Print a console banner (default true). */
+    banner?: boolean;
+}
+interface Pulse {
+    controller: PulseController;
+    bus: EventBus;
+    overlay: FlashOverlay | null;
+    solid: SolidInstrumentation | null;
+    bridge: BridgeClient | null;
+    /** Run a command exactly as the CLI would. */
+    run: PulseController["run"];
+    destroy(): void;
+}
+declare function getPulse(): Pulse | null;
+declare function initPulse(options?: PulseOptions): Pulse;
+declare global {
+    interface Window {
+        __SOLID_PULSE__?: Pulse;
+    }
+}
+
+export { ComponentRef, ElementRef, EventBus, Feature, FlashOverlay, type Pulse, PulseController, type PulseOptions, Rect, type SolidInstrumentation, describeElement, getPulse, initPulse, toSelector };