@epoch32/visage 0.0.0-stage → 1.0.0

package/src/devtools/component.tsx

@@ -0,0 +1,243 @@
+import { onCleanup, signal } from "../signals";
+import { Style } from "../style";
+import { Tabs } from "../ui/tabs";
+import { Tooltip } from "../ui/tooltip";
+import { DomTab } from "./DomTab";
+import { GraphTab } from "./GraphTab";
+import { setupDomMutationHighlighter } from "./highlighter";
+import { devtoolsHub } from "./hub";
+import { QueryTab } from "./QueryTab";
+import { RpcTab } from "./RpcTab";
+import { SignalsTab } from "./SignalsTab";
+import { devtoolsStyles } from "./styles";
+import type { DevToolsOptions, DevToolsTab } from "./types";
+
+export function VisageDevTools(props: DevToolsOptions = {}) {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  const hub = devtoolsHub;
+  if (typeof window !== "undefined" && !(window as any).__VISAGE_DEVTOOLS__) {
+    (window as any).__VISAGE_DEVTOOLS__ = hub;
+  }
+  if (props.initialOpen !== undefined) {
+    hub.isOpen.set(props.initialOpen);
+  }
+  if (props.initialTab !== undefined) {
+    hub.activeTab.set(props.initialTab);
+  }
+  if (props.highlightDOM !== undefined) {
+    hub.highlightDOM.set(props.highlightDOM);
+  }
+
+  // Set up real-time visual DOM mutation highlighting
+  setupDomMutationHighlighter(() => hub.highlightDOM());
+
+  const selectedId = signal<string | null>(null, { internal: true });
+  const searchQuery = signal("", { internal: true });
+
+  // Keyboard shortcut: Shift + Alt + V to toggle DevTools
+  if (typeof window !== "undefined") {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.shiftKey && e.altKey && e.key.toLowerCase() === "v") {
+        e.preventDefault();
+        hub.toggle();
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    onCleanup(() => window.removeEventListener("keydown", handleKeyDown));
+  }
+
+  const formatJSON = (val: any) => {
+    try {
+      if (val === undefined) return "undefined";
+      return JSON.stringify(val, null, 2);
+    } catch {
+      return String(val);
+    }
+  };
+
+  return (
+    <div class="visage-devtools-root">
+      <Style>{devtoolsStyles}</Style>
+
+      {/* Floating Toggle Launcher Button with Tooltip */}
+      {() =>
+        !hub.isOpen() ? (
+          <Tooltip content="Press Shift+Alt+V to toggle Visage DevTools" side="top">
+            <button
+              type="button"
+              class="visage-devtools-trigger"
+              onClick={() => hub.toggle()}
+              aria-label="Open Visage DevTools"
+            >
+              <svg
+                aria-hidden="true"
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z" />
+              </svg>
+              <span>DevTools</span>
+            </button>
+          </Tooltip>
+        ) : (
+          <div class="visage-devtools-drawer" role="dialog" aria-label="Visage In-Browser DevTools">
+            {/* Header with Navigation Tabs */}
+            <div class="visage-devtools-header">
+              <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
+                <svg
+                  aria-hidden="true"
+                  width="14"
+                  height="14"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="#38bdf8"
+                  stroke-width="2"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                >
+                  <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z" />
+                </svg>
+                <strong
+                  style={{
+                    fontSize: "12px",
+                    letterSpacing: "0.04em",
+                    color: "#f8fafc",
+                    fontWeight: 700
+                  }}
+                >
+                  VISAGE
+                </strong>
+              </div>
+
+              {/* DevTools Tab Bar powered by visage/ui <Tabs> */}
+              <Tabs
+                value={() => hub.activeTab()}
+                onValueChange={(val) => {
+                  hub.setTab(val as DevToolsTab);
+                  selectedId.set(null);
+                }}
+                listClass="visage-devtools-tabs"
+                items={[
+                  {
+                    value: "signals",
+                    label: () => (
+                      <span style={{ display: "inline-flex", alignItems: "center", gap: "6px" }}>
+                        <span>Signals</span>
+                        <span class="visage-devtools-badge">{() => hub.signalsList().length}</span>
+                      </span>
+                    )
+                  },
+                  {
+                    value: "graph",
+                    label: () => (
+                      <span style={{ display: "inline-flex", alignItems: "center", gap: "6px" }}>
+                        <span>DAG Graph</span>
+                        <span
+                          class="visage-devtools-badge"
+                          style={{ background: "#581c87", color: "#fff" }}
+                        >
+                          LIVE
+                        </span>
+                      </span>
+                    )
+                  },
+                  {
+                    value: "query",
+                    label: () => (
+                      <span style={{ display: "inline-flex", alignItems: "center", gap: "6px" }}>
+                        <span>Query Cache</span>
+                        <span class="visage-devtools-badge">{() => hub.queriesList().length}</span>
+                      </span>
+                    )
+                  },
+                  {
+                    value: "rpc",
+                    label: () => (
+                      <span style={{ display: "inline-flex", alignItems: "center", gap: "6px" }}>
+                        <span>RPC</span>
+                        <span class="visage-devtools-badge">{() => hub.rpcLogs().length}</span>
+                      </span>
+                    )
+                  },
+                  {
+                    value: "dom",
+                    label: "DOM Inspector"
+                  }
+                ]}
+              />
+
+              {/* Close Button */}
+              <div class="visage-devtools-actions">
+                <button
+                  type="button"
+                  class="visage-devtools-btn"
+                  onClick={() => hub.isOpen.set(false)}
+                  title="Close DevTools (Shift+Alt+V)"
+                >
+                  Close
+                </button>
+              </div>
+            </div>
+
+            {/* DevTools Body Switch */}
+            <div class="visage-devtools-body">
+              {() => {
+                const tab = hub.activeTab();
+                if (tab === "signals") {
+                  return (
+                    <SignalsTab
+                      hub={hub}
+                      selectedId={selectedId}
+                      searchQuery={searchQuery}
+                      formatJSON={formatJSON}
+                    />
+                  );
+                }
+                if (tab === "graph") {
+                  return (
+                    <GraphTab
+                      hub={hub}
+                      selectedId={selectedId}
+                      searchQuery={searchQuery}
+                      formatJSON={formatJSON}
+                    />
+                  );
+                }
+                if (tab === "query") {
+                  return (
+                    <QueryTab
+                      hub={hub}
+                      selectedId={selectedId}
+                      searchQuery={searchQuery}
+                      formatJSON={formatJSON}
+                    />
+                  );
+                }
+                if (tab === "rpc") {
+                  return (
+                    <RpcTab
+                      hub={hub}
+                      selectedId={selectedId}
+                      searchQuery={searchQuery}
+                      formatJSON={formatJSON}
+                    />
+                  );
+                }
+                return <DomTab hub={hub} />;
+              }}
+            </div>
+          </div>
+        )
+      }
+    </div>
+  );
+}

package/src/devtools/highlighter.ts

@@ -0,0 +1,134 @@
+import { effect, onCleanup } from "../signals";
+
+/**
+ * Visual DOM element mutation highlighter for Visage DevTools
+ */
+let styleInjected = false;
+const activeTimeouts = new WeakMap<Element, ReturnType<typeof setTimeout>>();
+
+function injectHighlighterStyles() {
+  if (styleInjected || typeof document === "undefined") return;
+  const style = document.createElement("style");
+  style.id = "visage-devtools-highlighter";
+  style.textContent = `
+    @keyframes visage-devtools-flash {
+      0% {
+        outline: 2px solid rgba(56, 189, 248, 0.9);
+        box-shadow: 0 0 12px rgba(56, 189, 248, 0.45);
+      }
+      100% {
+        outline: 2px solid transparent;
+        box-shadow: none;
+      }
+    }
+    .visage-dev-highlight {
+      outline-offset: -1px;
+      animation: visage-devtools-flash 0.5s ease-out !important;
+    }
+  `;
+  document.head.appendChild(style);
+  styleInjected = true;
+}
+
+export function highlightElement(element: Element | null) {
+  if (!element || typeof document === "undefined" || !(element instanceof Element)) return;
+  injectHighlighterStyles();
+
+  const prevTimeout = activeTimeouts.get(element);
+  if (prevTimeout) {
+    clearTimeout(prevTimeout);
+  }
+
+  element.classList.remove("visage-dev-highlight");
+  // Force reflow
+  void (element as HTMLElement).offsetWidth;
+  element.classList.add("visage-dev-highlight");
+
+  const timeout = setTimeout(() => {
+    element.classList.remove("visage-dev-highlight");
+    activeTimeouts.delete(element);
+  }, 500);
+
+  activeTimeouts.set(element, timeout);
+}
+
+let observer: MutationObserver | null = null;
+
+export function setupDomMutationHighlighter(enabledGetter: () => boolean) {
+  if (typeof window === "undefined" || typeof MutationObserver === "undefined") return;
+
+  const startObserver = () => {
+    if (observer) return;
+    injectHighlighterStyles();
+    observer = new MutationObserver((mutations) => {
+      if (!enabledGetter()) return;
+      const seen = new Set<Element>();
+      for (const mutation of mutations) {
+        const target = mutation.target as Node;
+        let el: Element | null = null;
+        if (target instanceof Element) {
+          el = target;
+        } else if (target.parentElement) {
+          el = target.parentElement;
+        }
+
+        if (!el) continue;
+
+        // Skip DevTools UI itself
+        if (el.closest?.(".visage-devtools-root") || el.closest?.("#visage-devtools-highlighter")) {
+          continue;
+        }
+
+        // Avoid infinite loops when adding/removing the highlight class
+        if (mutation.type === "attributes" && mutation.attributeName === "class") {
+          const oldCls = (mutation.oldValue || "")
+            .replace(/\bvisage-dev-highlight\b/g, "")
+            .replace(/\s+/g, " ")
+            .trim();
+          const newCls = (el.getAttribute("class") || "")
+            .replace(/\bvisage-dev-highlight\b/g, "")
+            .replace(/\s+/g, " ")
+            .trim();
+          if (oldCls === newCls) {
+            continue;
+          }
+        }
+
+        if (!seen.has(el)) {
+          seen.add(el);
+          highlightElement(el);
+        }
+      }
+    });
+
+    const targetNode = document.body || document.documentElement;
+    if (targetNode) {
+      observer.observe(targetNode, {
+        childList: true,
+        attributes: true,
+        attributeOldValue: true,
+        characterData: true,
+        subtree: true
+      });
+    }
+  };
+
+  const stopObserver = () => {
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
+  };
+
+  effect(() => {
+    if (enabledGetter()) {
+      startObserver();
+    } else {
+      stopObserver();
+    }
+  });
+
+  onCleanup(() => {
+    stopObserver();
+  });
+}

package/src/devtools/hub.ts

@@ -0,0 +1,175 @@
+import type { QueryClient } from "../query/query-client";
+import { signal } from "../signals";
+import type { DevToolsTab, QueryRecord, RpcRecord, SignalRecord } from "./types";
+
+export class DevToolsHub {
+  readonly isOpen = signal(false, { internal: true });
+  readonly activeTab = signal<DevToolsTab>("signals", { internal: true });
+  readonly highlightDOM = signal(false, { internal: true });
+  readonly searchQuery = signal("", { internal: true });
+
+  // Store active records
+  private _signalsMap = new Map<string, SignalRecord>();
+  readonly signalsList = signal<SignalRecord[]>([], { internal: true });
+
+  private _queriesMap = new Map<string, QueryRecord>();
+  readonly queriesList = signal<QueryRecord[]>([], { internal: true });
+
+  readonly rpcLogs = signal<RpcRecord[]>([], { internal: true });
+  private _queryClients = new Set<QueryClient>();
+
+  private _signalCounter = 0;
+
+  constructor() {
+    if (typeof window !== "undefined") {
+      (window as any).__VISAGE_DEVTOOLS__ = this;
+    }
+  }
+
+  toggle() {
+    this.isOpen.update((v) => !v);
+  }
+
+  setTab(tab: DevToolsTab) {
+    this.activeTab.set(tab);
+  }
+
+  // --- Signal Tracking ---
+  registerSignal(options: {
+    id?: string;
+    name?: string;
+    type?: "signal" | "computed";
+    getValue: () => any;
+    version: () => number;
+    dependencies?: () => string[];
+    dependents?: () => string[];
+    subscribersCount?: () => number;
+  }): string {
+    const id = options.id ?? `sig_${++this._signalCounter}`;
+    const name = options.name ?? id;
+    const type = options.type ?? "signal";
+
+    const record: SignalRecord = {
+      id,
+      name,
+      type,
+      getValue: options.getValue,
+      version: options.version,
+      dependencies: options.dependencies,
+      dependents: options.dependents,
+      subscribersCount: options.subscribersCount,
+      lastUpdatedAt: Date.now()
+    };
+
+    this._signalsMap.set(id, record);
+    this.refreshSignals();
+    return id;
+  }
+
+  unregisterSignal(id: string) {
+    if (this._signalsMap.delete(id)) {
+      this.refreshSignals();
+    }
+  }
+
+  clearSignals() {
+    this._signalsMap.clear();
+    this._signalCounter = 0;
+    this.refreshSignals();
+  }
+
+  clearQueries() {
+    this._queriesMap.clear();
+    this.queriesList.set([]);
+  }
+
+  clearAll() {
+    this.clearSignals();
+    this.clearQueries();
+    this.clearLogs();
+  }
+
+  private refreshSignals() {
+    this.signalsList.set(Array.from(this._signalsMap.values()));
+  }
+
+  // --- Query Cache Tracking ---
+  attachQueryClient(client: QueryClient) {
+    if (this._queryClients.has(client)) return;
+    this._queryClients.add(client);
+
+    const syncQueries = () => {
+      const cache = client.getQueryCache();
+      const allQueries = cache.getAll();
+      const records: QueryRecord[] = allQueries.map((q) => ({
+        hash: q.queryHash,
+        key: q.queryKey,
+        status: () => q.status(),
+        fetchStatus: () => q.fetchStatus(),
+        data: () => q.data(),
+        error: () => q.error(),
+        dataUpdatedAt: () => q.dataUpdatedAt(),
+        refetch: () => q.fetch(),
+        invalidate: () => q.invalidate()
+      }));
+
+      this._queriesMap.clear();
+      for (const r of records) {
+        this._queriesMap.set(r.hash, r);
+      }
+      this.queriesList.set(records);
+    };
+
+    client.getQueryCache().subscribe(() => {
+      syncQueries();
+    });
+
+    syncQueries();
+  }
+
+  // --- RPC & SSE Logging ---
+  logRpcCall(record: Omit<RpcRecord, "status" | "startTime"> & { status?: RpcRecord["status"] }) {
+    const fullRecord: RpcRecord = {
+      ...record,
+      status: record.status ?? "pending",
+      startTime: Date.now(),
+      events: []
+    };
+
+    this.rpcLogs.update((prev) => [fullRecord, ...prev.slice(0, 99)]);
+    return fullRecord.id;
+  }
+
+  updateRpcCall(id: string, updates: Partial<RpcRecord>) {
+    this.rpcLogs.update((prev) =>
+      prev.map((item) => {
+        if (item.id === id) {
+          const duration =
+            updates.duration ?? (updates.status ? Date.now() - item.startTime : item.duration);
+          return { ...item, ...updates, duration };
+        }
+        return item;
+      })
+    );
+  }
+
+  logRpcEvent(id: string, data: any) {
+    this.rpcLogs.update((prev) =>
+      prev.map((item) => {
+        if (item.id === id) {
+          const events = item.events
+            ? [...item.events, { timestamp: Date.now(), data }]
+            : [{ timestamp: Date.now(), data }];
+          return { ...item, events, status: "streaming" as const };
+        }
+        return item;
+      })
+    );
+  }
+
+  clearLogs() {
+    this.rpcLogs.set([]);
+  }
+}
+
+export const devtoolsHub = new DevToolsHub();

package/src/devtools/index.ts

@@ -0,0 +1,20 @@
+import type { QueryClient } from "../query/query-client";
+import { devtoolsHub } from "./hub";
+
+export { VisageDevTools } from "./component";
+export { highlightElement } from "./highlighter";
+export { DevToolsHub, devtoolsHub } from "./hub";
+export type {
+  DevToolsOptions,
+  DevToolsTab,
+  QueryRecord,
+  RpcRecord,
+  SignalRecord
+} from "./types";
+
+/**
+ * Connect QueryClient or RPC client to Visage DevTools
+ */
+export function connectDevTools(client: QueryClient) {
+  devtoolsHub.attachQueryClient(client);
+}