@yoltra/devtools-ui 0.2.0

package/dist/types/hooks/useStoreRegistry.d.ts

@@ -0,0 +1,33 @@
+import { RegisteredStore } from '../types';
+/**
+ * Tracks connected stores from `STORE_REGISTRY` hub broadcasts.
+ *
+ * @remarks
+ * The hook listens for three message types:
+ * - `STORE_REGISTRY` -- replaces the full store list (sent on initial connect).
+ * - `STORE_CONNECTED` -- adds or updates a single store entry.
+ * - `STORE_DISCONNECTED` -- marks a store as `"disconnected"`.
+ *
+ * The returned array is referentially stable unless the underlying data changes.
+ *
+ * @example
+ * ```tsx
+ * import { useStoreRegistry } from "@yoltra/devtools-ui";
+ *
+ * function StoreList() {
+ *   const stores = useStoreRegistry();
+ *   return (
+ *     <ul>
+ *       {stores.map((s) => (
+ *         <li key={s.id}>{s.name} ({s.status})</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @returns The current list of registered stores (see {@link RegisteredStore}).
+ *
+ * @public
+ */
+export declare function useStoreRegistry(): RegisteredStore[];

package/dist/types/hooks/useStoreState.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Hook that provides a live, incrementally-patched view of a store's state.
+ *
+ * @remarks
+ * On activation, the hook requests a full `STATE_SNAPSHOT` from the hub.
+ * While waiting, any `STORE_EVENT` patches that arrive are buffered and
+ * replayed once the snapshot lands. After that, each committed patch is
+ * applied via {@link applyPatches} so the UI always reflects the latest
+ * store state without requiring full snapshots.
+ *
+ * @module @yoltra/devtools-ui
+ */
+/**
+ * Lazily fetches a store's full state and keeps it up-to-date via patches.
+ *
+ * @remarks
+ * The state is initially `null` until a `STATE_SNAPSHOT` is received.
+ * After that, incoming `STORE_EVENT` patches are applied incrementally
+ * using {@link applyPatches}. Patches that arrive before the snapshot are
+ * buffered and replayed in version order once the snapshot is available.
+ *
+ * Call `refresh()` to discard the current state and re-fetch from scratch.
+ *
+ * @example
+ * ```tsx
+ * import { useStoreState } from "@yoltra/devtools-ui";
+ *
+ * function StateInspector({ storeId }: { storeId: string }) {
+ *   const { state, version, loading, refresh } = useStoreState(storeId);
+ *   if (loading) return <p>Loading...</p>;
+ *   return (
+ *     <div>
+ *       <p>Version: {version}</p>
+ *       <pre>{JSON.stringify(state, null, 2)}</pre>
+ *       <button onClick={refresh}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param storeId - The store ID to track state for, or `null` to disable.
+ * @returns An object with `state`, `version`, `loading`, and `refresh`.
+ *
+ * @public
+ */
+export declare function useStoreState(storeId: string | null): {
+    state: unknown;
+    version: number;
+    loading: boolean;
+    refresh: () => void;
+};

package/dist/types/hooks/useStoreSubscriptions.d.ts

@@ -0,0 +1,45 @@
+import { StoreSubscriptions } from '@yoltra/devtools-protocol';
+/**
+ * Subscription data payload with protocol envelope fields stripped.
+ *
+ * @internal
+ */
+type SubscriptionData = Omit<StoreSubscriptions, "type" | "timestamp" | "sourceId" | "sourceRole" | "storeId">;
+/**
+ * Fetches and caches subscription/consumer info for a store.
+ *
+ * @remarks
+ * On mount (or when `storeId` changes) the hook sends a
+ * `REQUEST_SUBSCRIPTIONS` message and sets `loading` to `true`. When the
+ * matching `STORE_SUBSCRIPTIONS` response arrives the data is cached and
+ * `loading` flips to `false`.
+ *
+ * @example
+ * ```tsx
+ * import { useStoreSubscriptions } from "@yoltra/devtools-ui";
+ *
+ * function SubscriptionPanel({ storeId }: { storeId: string }) {
+ *   const { data, loading, refresh } = useStoreSubscriptions(storeId);
+ *   if (loading || !data) return <p>Loading...</p>;
+ *   return (
+ *     <div>
+ *       <p>Atomic: {data.atomic.length}</p>
+ *       <p>Event: {data.event.length}</p>
+ *       <button onClick={refresh}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param storeId - The store ID to query, or `null` to disable.
+ * @returns An object with `data` ({@link SubscriptionData} or `null`),
+ *   `loading`, and `refresh`.
+ *
+ * @public
+ */
+export declare function useStoreSubscriptions(storeId: string | null): {
+    data: SubscriptionData | null;
+    loading: boolean;
+    refresh: () => void;
+};
+export {};

package/dist/types/hooks/useTimeTravel.d.ts

@@ -0,0 +1,67 @@
+import { EventLogEntry } from '../types';
+/**
+ * Provides time-travel navigation through the event log.
+ *
+ * @remarks
+ * The hook tracks whether the user is actively time-traveling via
+ * `isTimeTraveling`. While traveling, `currentIndex` indicates the position
+ * within the `entries` array. The `stepBack` / `stepForward` helpers move
+ * one entry at a time, while `jumpTo` allows arbitrary positioning. Calling
+ * `resume()` exits time-travel mode, jumps to the latest entry, and resets
+ * the index to `-1`.
+ *
+ * @example
+ * ```tsx
+ * import { useEventLog, useTimeTravel } from "@yoltra/devtools-ui";
+ *
+ * function TimeTravelControls({ storeId }: { storeId: string }) {
+ *   const { entries } = useEventLog(storeId);
+ *   const { currentIndex, isTimeTraveling, stepBack, stepForward, resume } =
+ *     useTimeTravel(storeId, entries);
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={stepBack} disabled={currentIndex <= 0}>Back</button>
+ *       <button onClick={stepForward}>Forward</button>
+ *       {isTimeTraveling && <button onClick={resume}>Resume Live</button>}
+ *       <span>Index: {currentIndex} / {entries.length - 1}</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param storeId - The store ID to time-travel, or `null` to disable.
+ * @param entries - The event log entries (typically from {@link useEventLog}).
+ * @returns An object with `currentIndex`, `isTimeTraveling`, `jumpTo`,
+ *   `stepBack`, `stepForward`, and `resume`.
+ *
+ * @public
+ */
+export declare function useTimeTravel(storeId: string | null, entries: EventLogEntry[], 
+/**
+ * Whether the selected store advertised the `replay` capability. Time-travel
+ * commands are gated on it (DEV-4): the agent/core enforce it too, but the UI
+ * should not send commands that will be dropped. Defaults to `true`.
+ */
+canReplay?: boolean): {
+    currentIndex: number;
+    isTimeTraveling: boolean;
+    /**
+     * The store state reconstructed at the currently-viewed position (the
+     * scrubbed index while traveling, otherwise the latest entry). `null` until
+     * the baseline snapshot has been captured. Lets consumers render a live
+     * preview of the state at any point in history.
+     */
+    previewState: unknown;
+    /**
+     * The event count the timeline is measured against: frozen at travel-start
+     * so a live-emitting store cannot shift the scrubber, or `null` when live
+     * (use `entries.length`). Consumers should size the slider/label off
+     * `frameCount ?? entries.length`.
+     */
+    frameCount: number | null;
+    jumpTo: (index: number) => void;
+    stepBack: () => void;
+    stepForward: () => void;
+    resume: () => void;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module @yoltra/devtools-ui
+ *
+ * Shared React hooks and business logic for Yoltra DevTools UIs.
+ * Used by both `@yoltra/devtools-storeview` (React DOM) and `@yoltra/devtools-cli` (Ink).
+ * This package contains no UI components — only logic.
+ */
+export { HubContext } from './context/HubContext';
+export { HubProvider } from './context/HubProvider';
+export { useEventEmitter } from './hooks/useEventEmitter';
+export { useEventLog } from './hooks/useEventLog';
+export { useEventReplay } from './hooks/useEventReplay';
+export { useHubConnection } from './hooks/useHubConnection';
+export { useStoreMetrics } from './hooks/useStoreMetrics';
+export { useStoreRegistry } from './hooks/useStoreRegistry';
+export { useStoreState } from './hooks/useStoreState';
+export { useStoreSubscriptions } from './hooks/useStoreSubscriptions';
+export { useTimeTravel } from './hooks/useTimeTravel';
+export { applyPatches } from './utils/apply-patch';
+export { createLoopbackHub } from './transport/loopback';
+export type { LoopbackHub } from './transport/loopback';
+export type { EventLogEntry, HubConnectionConfig, HubConnectionStatus, HubContextValue, RegisteredStore, } from './types';
+export type { UseEventLogOptions } from './hooks/useEventLog';
+export type { UseStoreMetricsOptions } from './hooks/useStoreMetrics';

package/dist/types/transport/loopback.d.ts

@@ -0,0 +1,30 @@
+import { DevtoolsSocketFactory } from '@yoltra/devtools-protocol';
+/**
+ * A loopback hub instance. Wire the agent and the panel to the *same* instance.
+ *
+ * @public
+ */
+export interface LoopbackHub {
+    /** Inject into the browser agent: `withDevtools(store, { socketFactory })`. */
+    agentSocketFactory: DevtoolsSocketFactory;
+    /** Pass to the DevTools UI as `config.WebSocket` (e.g. `<DevtoolsApp>`). */
+    WebSocket: {
+        new (url: string): WebSocket;
+    };
+}
+/**
+ * Creates a self-contained in-memory DevTools hub plus the two client transports
+ * that connect to it — a `socketFactory` for the store agent and a
+ * `WebSocket`-compatible class for the panel UI. No ports, no server, no
+ * extension: everything runs in the current process.
+ *
+ * @example
+ * ```ts
+ * const hub = createLoopbackHub();
+ * withDevtools(store, { port: 0, socketFactory: hub.agentSocketFactory });
+ * // <DevtoolsApp config={{ port: 0, WebSocket: hub.WebSocket }} />
+ * ```
+ *
+ * @public
+ */
+export declare function createLoopbackHub(): LoopbackHub;

package/dist/types/types.d.ts

@@ -0,0 +1,138 @@
+import { DevtoolsMessage, StoreCapabilities, StoreEvent } from '@yoltra/devtools-protocol';
+/**
+ * Connection configuration for the DevTools hub.
+ *
+ * @remarks
+ * Pass this to {@link HubProvider} to control how the extension connects to
+ * the hub server. The only required field is `port`; all other fields have
+ * sensible defaults.
+ *
+ * @example
+ * ```tsx
+ * const config: HubConnectionConfig = {
+ *   port: 8900,
+ *   extensionName: "My Panel",
+ *   autoReconnect: true,
+ * };
+ *
+ * <HubProvider config={config}>
+ *   <App />
+ * </HubProvider>
+ * ```
+ *
+ * @public
+ */
+export interface HubConnectionConfig {
+    /** Hub server host. @defaultValue `"localhost"` */
+    host?: string;
+    /** Hub server port. */
+    port: number;
+    /** Display name for this extension instance. */
+    extensionName?: string;
+    /** Auto-reconnect on disconnect. @defaultValue `true` */
+    autoReconnect?: boolean;
+    /** Maximum reconnect attempts. @defaultValue `Infinity` */
+    maxReconnectAttempts?: number;
+    /**
+     * Custom WebSocket constructor for Node.js environments.
+     *
+     * @remarks
+     * In Node.js 18, the global `WebSocket` is not available. Pass the `WebSocket`
+     * class from the `ws` package to enable connectivity:
+     *
+     * ```ts
+     * import WebSocket from "ws";
+     * config.WebSocket = WebSocket as any;
+     * ```
+     *
+     * In browsers or Node.js 21+, this is not needed — the native `WebSocket` is
+     * used automatically.
+     */
+    WebSocket?: {
+        new (url: string): WebSocket;
+    };
+}
+/**
+ * Connection status for the hub WebSocket.
+ *
+ * @remarks
+ * - `"disconnected"` -- no active connection.
+ * - `"connecting"` -- WebSocket handshake in progress.
+ * - `"connected"` -- handshake complete, messages can be sent and received.
+ *
+ * @public
+ */
+export type HubConnectionStatus = "disconnected" | "connecting" | "connected";
+/**
+ * Registered store entry tracked by the store registry.
+ *
+ * @remarks
+ * Populated automatically by the {@link useStoreRegistry} hook in response to
+ * `STORE_REGISTRY`, `STORE_CONNECTED`, and `STORE_DISCONNECTED` hub messages.
+ *
+ * @public
+ */
+export interface RegisteredStore {
+    /** Unique store identifier assigned by the hub. */
+    id: string;
+    /** Human-readable store name. */
+    name: string;
+    /** Current connectivity status of the store. */
+    status: "connected" | "connecting" | "disconnected";
+    /** Capabilities advertised by the store during handshake. */
+    capabilities: StoreCapabilities;
+    /** ISO-8601 timestamp of when the store first connected. */
+    connectedAt: string;
+}
+/**
+ * A logged event entry in the event log.
+ *
+ * @remarks
+ * Each entry captures a single `STORE_EVENT` message received from the hub,
+ * including the event descriptor, resulting patches, and the snapshot version
+ * after the event was applied. The {@link useEventLog} hook collects these
+ * entries in chronological order.
+ *
+ * @public
+ */
+export interface EventLogEntry {
+    /** The event descriptor (channel, type, payload). */
+    event: StoreEvent["event"];
+    /** Identifier of the store that emitted the event. */
+    storeId: string;
+    /** JSON Patch operations produced by the event. */
+    patches: StoreEvent["patches"];
+    /** Store snapshot version after this event was applied. */
+    snapshotVersion: number;
+    /** Whether the event was committed to the store. */
+    committed: boolean;
+    /** ISO-8601 timestamp of the event. */
+    timestamp: string;
+}
+/**
+ * Hub connection context value provided to consumers.
+ *
+ * @remarks
+ * This is the shape of the value exposed by {@link HubContext} and consumed
+ * via {@link useHubConnection}. It contains methods for sending messages,
+ * subscribing to incoming messages, and controlling the connection lifecycle.
+ *
+ * @public
+ */
+export interface HubContextValue {
+    /** Current connection status. */
+    status: HubConnectionStatus;
+    /** Send a protocol message to the hub. */
+    send: (message: DevtoolsMessage) => void;
+    /**
+     * Subscribe to incoming hub messages.
+     *
+     * @param handler - Callback invoked for every incoming message.
+     * @returns An unsubscribe function.
+     */
+    subscribe: (handler: (message: DevtoolsMessage) => void) => () => void;
+    /** Manually disconnect from the hub and cancel auto-reconnect. */
+    disconnect: () => void;
+    /** Reset reconnect attempts and establish a fresh connection. */
+    reconnect: () => void;
+}

package/dist/types/utils/apply-patch.d.ts

@@ -0,0 +1,30 @@
+import { JsonPatch } from '@yoltra/devtools-protocol';
+/**
+ * Apply an array of RFC 6902 JSON Patch operations to a value.
+ * Returns a new object -- does not mutate the input.
+ *
+ * @remarks
+ * Only the `add`, `remove`, and `replace` operations are implemented because
+ * the v1 devtools protocol does not emit `move`, `copy`, or `test` patches.
+ * Each operation is applied sequentially in array order. Path segments are
+ * resolved according to RFC 6901 (JSON Pointer), including `~0` / `~1`
+ * escape handling.
+ *
+ * @example
+ * ```ts
+ * import { applyPatches } from "@yoltra/devtools-ui";
+ *
+ * const next = applyPatches(
+ *   { counter: { value: 0 } },
+ *   [{ op: "replace", path: "/counter/value", value: 1 }],
+ * );
+ * // next => { counter: { value: 1 } }
+ * ```
+ *
+ * @param target - The value to patch.
+ * @param patches - RFC 6902 operations.
+ * @returns A new patched value.
+ *
+ * @public
+ */
+export declare function applyPatches<T = unknown>(target: T, patches: JsonPatch[]): T;

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@yoltra/devtools-ui",
+  "version": "0.2.0",
+  "description": "Shared React hooks and business logic for Yoltra DevTools UIs",
+  "license": "MIT",
+  "author": {
+    "name": "Manu Ramirez <@pixerael>",
+    "email": "manu@yoltra.dev"
+  },
+  "maintainers": [],
+  "homepage": "https://yoltra.dev",
+  "keywords": [
+    "yoltra",
+    "devtools",
+    "ui",
+    "hooks"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yoltra/yoltra.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yoltra/yoltra/issues"
+  },
+  "type": "module",
+  "main": "dist/devtools-ui.cjs.js",
+  "module": "dist/devtools-ui.esm.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/devtools-ui.esm.js",
+      "require": "./dist/devtools-ui.cjs.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "dependencies": {
+    "@yoltra/devtools-protocol": "0.2.0"
+  },
+  "devDependencies": {
+    "react": "19.1.1",
+    "@types/react": "^19.1.8",
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-markdown": "4.9.0",
+    "typedoc-plugin-localization": "3.0.6",
+    "typescript": "5.9.3",
+    "vite": "^7.1.11",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-banner": "0.8.1",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest --watch=false",
+    "lint": "node ../../tools/repo-tools/bin/repo-eslint.cjs --report-unused-disable-directives --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "docs": "rushx docs:js && rushx docs:md",
+    "docs:md": "pnpm typedoc --options ./typedoc.json",
+    "docs:js": "pnpm typedoc --options ./typedoc.json --json ./.typedoc/devtools-ui-en.json"
+  }
+}