@praxisjs/devtools 0.1.0

package/src/index.ts

@@ -0,0 +1,20 @@
+export { DevTools } from "@/ui/dev-tools";
+export type { DevToolsOptions } from "@/ui/dev-tools";
+
+export { Debug, Trace } from "@/decorators";
+export type { DebugOptions } from "@/decorators/debug";
+
+export { Registry } from "@/core/registry";
+export type {
+  SignalEntry,
+  ComponentEntry,
+  TimelineEntry,
+  HistoryEntry,
+  LifecycleEvent,
+  TimelineEventType,
+} from "@/core/types";
+export type { DevtoolsPlugin } from "@/plugins/types";
+
+export { SignalsPlugin } from "@/plugins/signals";
+export { ComponentsPlugin } from "@/plugins/components";
+export { TimelinePlugin } from "@/plugins/timeline";

package/src/plugins/components/components/component-detail.tsx

@@ -0,0 +1,70 @@
+import { SidePanel } from "@shared/side-panel";
+import { formatValue } from "@utils/format-value";
+
+import { DetailRow } from "./detail-row";
+import { DetailSection } from "./detail-section";
+import { StatusDot } from "./status-dot";
+
+import type { ComponentEntry, SignalEntry } from "@core/types";
+
+export function ComponentDetail({
+  entry,
+  signals,
+}: {
+  entry: ComponentEntry;
+  signals: SignalEntry[];
+}) {
+  return (
+    <SidePanel>
+      <div class="px-3 py-2 border-b border-border flex items-center gap-2 bg-bg shrink-0">
+        <StatusDot status={entry.status} />
+        <span class="text-accent font-mono text-[11px] font-semibold truncate pl-1">
+          &lt;{entry.name}&gt;
+        </span>
+      </div>
+
+      <div class="flex-1 overflow-y-auto">
+        <DetailSection label="Stats">
+          <DetailRow k="renders" v={String(entry.renderCount)} />
+          <DetailRow
+            k="last render"
+            v={`${entry.lastRenderDuration.toFixed(3)}ms`}
+          />
+          <DetailRow k="status" v={entry.status} />
+        </DetailSection>
+
+        {signals.length > 0 && (
+          <DetailSection label="State">
+            {signals.map((s) => (
+              <DetailRow
+                key={s.id}
+                k={s.label}
+                v={formatValue(s.value)}
+                signal
+              />
+            ))}
+          </DetailSection>
+        )}
+
+        {entry.lifecycle.length > 0 && (
+          <DetailSection label="Lifecycle">
+            {[...entry.lifecycle]
+              .reverse()
+              .slice(0, 20)
+              .map((ev, i) => (
+                <div
+                  key={String(i)}
+                  class="px-3 py-2 flex justify-between items-center border-b border-border"
+                >
+                  <span class="text-[11px] text-text font-mono">{ev.hook}</span>
+                  <span class="text-[10px] text-subtle tabular-nums">
+                    {new Date(ev.timestamp).toLocaleTimeString()}
+                  </span>
+                </div>
+              ))}
+          </DetailSection>
+        )}
+      </div>
+    </SidePanel>
+  );
+}

package/src/plugins/components/components/component-row.tsx

@@ -0,0 +1,42 @@
+import { StatusDot } from "./status-dot";
+
+import type { ComponentEntry } from "@core/types";
+
+export function ComponentRow({
+  entry,
+  selected,
+  onClick,
+}: {
+  entry: ComponentEntry;
+  selected: () => boolean;
+  onClick: () => void;
+}) {
+  return (
+    <div
+      onClick={onClick}
+      class={() =>
+        `relative flex items-center gap-2 px-3 py-2 cursor-pointer border-b border-border transition-colors duration-100 ${
+          selected() ? "bg-selected" : "hover:bg-section"
+        }`
+      }
+    >
+      {() =>
+        selected() && (
+          <span class="absolute left-0 top-0 bottom-0 w-[2px] bg-accent rounded-r" />
+        )
+      }
+      <StatusDot status={entry.status} />
+      <span class="text-accent font-mono text-[11px] flex-1 truncate pl-1">
+        &lt;{entry.name}&gt;
+      </span>
+      <span class="text-muted text-[11px] tabular-nums">
+        ×{entry.renderCount}
+      </span>
+      <span
+        class={`text-[10px] tabular-nums w-12 text-right ${entry.lastRenderDuration > 16 ? "text-warn" : "text-subtle"}`}
+      >
+        {entry.lastRenderDuration.toFixed(1)}ms
+      </span>
+    </div>
+  );
+}

package/src/plugins/components/components/detail-row.tsx

@@ -0,0 +1,22 @@
+export function DetailRow({
+  k,
+  v,
+  signal: isSignal,
+}: {
+  k: string;
+  v: string;
+  signal?: boolean;
+}) {
+  return (
+    <div class="flex justify-between items-center px-3 py-2 border-b border-border gap-3">
+      <span
+        class={`text-[11px] font-mono shrink-0 ${isSignal ? "text-accent" : "text-muted"}`}
+      >
+        {k}
+      </span>
+      <span class="text-[11px] text-text font-mono truncate text-right">
+        {v}
+      </span>
+    </div>
+  );
+}

package/src/plugins/components/components/detail-section.tsx

@@ -0,0 +1,18 @@
+import type { Children } from "@praxisjs/shared";
+
+export function DetailSection({
+  label,
+  children,
+}: {
+  label: string;
+  children: Children;
+}) {
+  return (
+    <div class="border-b border-border">
+      <div class="px-3 py-[4px] text-[9px] text-subtle font-bold tracking-[0.12em] uppercase bg-section border-b border-border">
+        {label}
+      </div>
+      {children}
+    </div>
+  );
+}

package/src/plugins/components/components/status-dot.tsx

@@ -0,0 +1,14 @@
+import type { ComponentEntry } from "@core/types";
+
+export function StatusDot({ status }: { status: ComponentEntry["status"] }) {
+  return (
+    <span
+      class={`inline-block w-[6px] h-[6px] rounded-full shrink-0 ${status === "mounted" ? "bg-success" : "bg-subtle"}`}
+      style={
+        status === "mounted"
+          ? { boxShadow: "0 0 6px rgba(14,165,122,0.7)" }
+          : undefined
+      }
+    />
+  );
+}

package/src/plugins/components/components-tab.tsx

@@ -0,0 +1,85 @@
+import { EmptyState } from "@shared/empty-state";
+
+import { signal, effect, peek, onMount, onUnmount } from "@praxisjs/core";
+
+import { ComponentDetail } from "./components/component-detail";
+import { ComponentRow } from "./components/component-row";
+
+import type { Registry } from "@core/registry";
+import type { ComponentEntry, SignalEntry } from "@core/types";
+
+export function ComponentsTab({ registry }: { registry: Registry }) {
+  const components = signal<ComponentEntry[]>(registry.getComponents());
+  const selectedId = signal<string | null>(null);
+  const sigs = signal<SignalEntry[]>([]);
+
+  const stopSigEffect = effect(() => {
+    const id = selectedId();
+    sigs.set(id ? registry.getSignalsByComponent(id) : []);
+  });
+
+  let handlers: Array<() => void> = [];
+  onMount(() => {
+    const refresh = () => {
+      components.set(registry.getComponents());
+      const id = peek(selectedId);
+      if (id) sigs.set(registry.getSignalsByComponent(id));
+    };
+    handlers = [
+      "component:registered",
+      "component:render",
+      "component:unmount",
+      "lifecycle",
+      "signal:registered",
+      "signal:changed",
+    ].map((ev) => registry.bus.on(ev, refresh));
+  });
+
+  onUnmount(() => {
+    stopSigEffect();
+    handlers.forEach((off) => {
+      off();
+    });
+  });
+
+  return (
+    <div class="flex h-full overflow-hidden">
+      <div class="flex-1 flex flex-col overflow-hidden min-w-0">
+        <div class="flex items-center px-3 h-7 text-[9px] text-subtle font-bold tracking-[0.12em] uppercase border-b border-border bg-section gap-2 shrink-0">
+          <span class="flex-1">Component</span>
+          <span>Renders</span>
+          <span class="w-12 text-right">Last</span>
+        </div>
+
+        <div class="flex-1 overflow-y-auto">
+          {() =>
+            components().length === 0 ? (
+              <EmptyState message="No components tracked. Add @Trace() to component classes." />
+            ) : (
+              components().map((c) => (
+                <ComponentRow
+                  key={c.id}
+                  entry={c}
+                  selected={() => selectedId() === c.id}
+                  onClick={() => {
+                    selectedId.update((id) => (id === c.id ? null : c.id));
+                  }}
+                />
+              ))
+            )
+          }
+        </div>
+      </div>
+
+      {() => {
+        const id = selectedId();
+        const entry = id
+          ? (components().find((c) => c.id === id) ?? null)
+          : null;
+        return entry ? (
+          <ComponentDetail entry={entry} signals={sigs()} />
+        ) : null;
+      }}
+    </div>
+  );
+}

package/src/plugins/components/index.ts

@@ -0,0 +1,9 @@
+import { ComponentsTab } from "./components-tab";
+
+import type { DevtoolsPlugin } from "@plugins/types";
+
+export const ComponentsPlugin: DevtoolsPlugin = {
+  id: "components",
+  label: "Components",
+  component: ComponentsTab,
+};

package/src/plugins/signals/components/signal-detail.tsx

@@ -0,0 +1,35 @@
+import { PanelSection } from "@shared/panel-section";
+import { SidePanel } from "@shared/side-panel";
+import { time } from "@utils/format-time";
+import { formatValue } from "@utils/format-value";
+
+import type { SignalEntry } from "@core/types";
+
+export function SignalDetail({ entry }: { entry: SignalEntry }) {
+  return (
+    <SidePanel width="260px">
+      <PanelSection label="History">
+        <div class="overflow-y-auto">
+          {[...entry.history].reverse().map((h, i) => (
+            <div
+              key={String(i)}
+              class="px-3 py-2 border-b border-border flex justify-between items-center gap-3"
+            >
+              <span class="font-mono text-[11px] text-text truncate">
+                {formatValue(h.value)}
+              </span>
+              <span class="text-[10px] text-subtle shrink-0 tabular-nums">
+                {time(h.timestamp, "ago")}
+              </span>
+            </div>
+          ))}
+          {entry.history.length === 0 && (
+            <p class="px-3 py-6 text-[11px] text-subtle text-center">
+              No history yet.
+            </p>
+          )}
+        </div>
+      </PanelSection>
+    </SidePanel>
+  );
+}

package/src/plugins/signals/components/signal-row.tsx

@@ -0,0 +1,37 @@
+import { time } from "@utils/format-time";
+import { formatValue } from "@utils/format-value";
+
+import type { SignalEntry } from "@core/types";
+
+export function SignalRow({
+  entry,
+  selected,
+  onClick,
+}: {
+  entry: SignalEntry;
+  selected: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <div
+      onClick={onClick}
+      class={`relative grid grid-cols-[1.2fr_0.8fr_1fr_auto] items-center px-3 py-2 cursor-pointer border-b border-border transition-colors duration-100 ${
+        selected ? "bg-selected" : "hover:bg-section"
+      }`}
+    >
+      {selected && (
+        <span class="absolute left-0 top-0 bottom-0 w-[2px] bg-accent rounded-r" />
+      )}
+      <span class="text-accent font-mono text-[11px] truncate pl-1">
+        {entry.label}
+      </span>
+      <span class="text-muted text-[11px] truncate">{entry.componentName}</span>
+      <span class="text-text font-mono text-[11px] truncate">
+        {formatValue(entry.value)}
+      </span>
+      <span class="text-subtle text-[10px] text-right tabular-nums">
+        {time(entry.changedAt, "ago")}
+      </span>
+    </div>
+  );
+}

package/src/plugins/signals/index.ts

@@ -0,0 +1,9 @@
+import { SignalsTab } from "./signals-tab";
+
+import type { DevtoolsPlugin } from "@plugins/types";
+
+export const SignalsPlugin: DevtoolsPlugin = {
+  id: "signals",
+  label: "Signals",
+  component: SignalsTab,
+};

package/src/plugins/signals/signals-tab.tsx

@@ -0,0 +1,99 @@
+import { EmptyState } from "@shared/empty-state";
+import { SearchInput } from "@shared/search-input";
+
+import { signal, onMount, onUnmount } from "@praxisjs/core";
+
+import { SignalDetail } from "./components/signal-detail";
+import { SignalRow } from "./components/signal-row";
+
+import type { Registry } from "@core/registry";
+import type { SignalEntry } from "@core/types";
+
+export function SignalsTab({ registry }: { registry: Registry }) {
+  const signals = signal<SignalEntry[]>(registry.getSignals());
+  const search = signal("");
+  const selectedId = signal<string | null>(null);
+
+  let handlers: Array<() => void> = [];
+  onMount(() => {
+    handlers = [
+      registry.bus.on("signal:registered", () => {
+        signals.set(registry.getSignals());
+      }),
+      registry.bus.on("signal:changed", () => {
+        signals.set(registry.getSignals());
+      }),
+    ];
+  });
+
+  onUnmount(() => {
+    handlers.forEach((off) => {
+      off();
+    });
+  });
+
+  return (
+    <div class="flex h-full overflow-hidden">
+      <div class="flex-1 flex flex-col overflow-hidden min-w-0">
+        <div class="px-3 py-2 border-b border-border bg-bg shrink-0">
+          <SearchInput
+            placeholder="Search signals…"
+            onInput={(v) => {
+              search.set(v);
+            }}
+          />
+        </div>
+
+        <div class="grid grid-cols-[1.2fr_0.8fr_1fr_auto] items-center px-3 h-7 text-[9px] text-subtle font-bold tracking-[0.12em] uppercase border-b border-border bg-section gap-2 shrink-0">
+          <span>Signal</span>
+          <span>Component</span>
+          <span>Value</span>
+          <span>Age</span>
+        </div>
+
+        <div class="flex-1 overflow-y-auto">
+          {() => {
+            const q = search().toLowerCase();
+            const filtered =
+              q === ""
+                ? signals()
+                : signals().filter(
+                    (s) =>
+                      s.label.toLowerCase().includes(q) ||
+                      s.componentName.toLowerCase().includes(q),
+                  );
+
+            if (filtered.length === 0) {
+              return (
+                <EmptyState
+                  message={
+                    signals().length === 0
+                      ? "No signals tracked. Add @Debug() on top of @State() properties."
+                      : "No signals match your search."
+                  }
+                />
+              );
+            }
+
+            return filtered.map((s) => (
+              <SignalRow
+                key={s.id}
+                entry={s}
+                selected={selectedId() === s.id}
+                onClick={() => {
+                  selectedId.update((id) => (id === s.id ? null : s.id));
+                }}
+              />
+            ));
+          }}
+        </div>
+      </div>
+
+      {() => {
+        const id = selectedId();
+        const entry = id ? (signals().find((s) => s.id === id) ?? null) : null;
+        return entry ? <SignalDetail entry={entry} /> : null;
+      }}
+    </div>
+  );
+}

package/src/plugins/timeline/components/badge.tsx

@@ -0,0 +1,14 @@
+import { TYPE_META } from "../constants";
+
+import type { TimelineEventType } from "@core/types";
+
+export function Badge({ type }: { type: TimelineEventType }) {
+  const meta = TYPE_META[type];
+  return (
+    <span
+      class={`text-[9px] px-[6px] py-[2px] rounded font-bold uppercase tracking-[0.07em] shrink-0 ${meta.cls}`}
+    >
+      {meta.label}
+    </span>
+  );
+}

package/src/plugins/timeline/components/timeline-row.tsx

@@ -0,0 +1,55 @@
+import { time } from "@utils/format-time";
+
+import { signal } from "@praxisjs/core";
+
+import { Badge } from "./badge";
+
+import type { TimelineEntry } from "@core/types";
+
+export function TimelineRow({ entry }: { entry: TimelineEntry }) {
+  const open = signal(false);
+  const hasData = Object.keys(entry.data).length > 0;
+
+  return (
+    <div class="border-b border-border">
+      <div
+        onClick={() => {
+          if (hasData) open.update((v) => !v);
+        }}
+        class={`flex items-center gap-2 px-3 py-2 transition-colors duration-100 ${
+          hasData ? "cursor-pointer hover:bg-section" : "cursor-default"
+        }`}
+      >
+        <span class="text-subtle text-[10px] w-10 shrink-0 text-right tabular-nums font-mono">
+          {time(entry.timestamp)}
+        </span>
+        <Badge type={entry.type} />
+        <span class="flex-1 text-text font-mono text-[11px] truncate">
+          {entry.label}
+        </span>
+        {hasData && (
+          <span class="text-subtle text-[11px] shrink-0 w-4 text-center">
+            {() => (open() ? "▾" : "▸")}
+          </span>
+        )}
+      </div>
+
+      {() =>
+        open() && hasData ? (
+          <div class="px-3 py-2 pl-[56px] font-mono text-[11px] bg-section border-t border-border">
+            {Object.entries(entry.data).map(([k, v]) => (
+              <div key={k} class="flex gap-3 py-[3px]">
+                <span class="text-accent shrink-0">{k}:</span>
+                <span class="text-muted truncate">
+                  {typeof v === "object"
+                    ? JSON.stringify(v)
+                    : String(v as unknown)}
+                </span>
+              </div>
+            ))}
+          </div>
+        ) : null
+      }
+    </div>
+  );
+}

package/src/plugins/timeline/constants.ts

@@ -0,0 +1,24 @@
+import type { TimelineEventType } from '../../core/types';
+
+export type Filter = TimelineEventType | 'all';
+
+export const TYPE_META: Record<
+  TimelineEventType,
+  { label: string; cls: string }
+> = {
+  'signal:change':    { label: 'signal',    cls: 'text-[#9b90e6] bg-[rgba(155,144,230,0.14)]' },
+  'component:render': { label: 'render',    cls: 'text-[#4ade80] bg-[rgba(74,222,128,0.12)]' },
+  'component:mount':  { label: 'mount',     cls: 'text-[#0ea57a] bg-[rgba(14,165,122,0.14)]' },
+  'component:unmount':{ label: 'unmount',   cls: 'text-[#dc2626] bg-[rgba(220,38,38,0.14)]' },
+  lifecycle:          { label: 'lifecycle', cls: 'text-[#d97706] bg-[rgba(217,119,6,0.14)]' },
+  'method:call':      { label: 'method',    cls: 'text-[#7c6dd6] bg-[rgba(124,109,214,0.14)]' },
+};
+
+export const FILTERS: Array<{ value: Filter; label: string }> = [
+  { value: 'all', label: 'All' },
+  { value: 'signal:change', label: 'Signals' },
+  { value: 'component:render', label: 'Renders' },
+  { value: 'component:mount', label: 'Mount' },
+  { value: 'lifecycle', label: 'Lifecycle' },
+  { value: 'method:call', label: 'Methods' },
+];

package/src/plugins/timeline/index.ts

@@ -0,0 +1,9 @@
+import { TimelineTab } from "./timeline-tab";
+
+import type { DevtoolsPlugin } from "@plugins/types";
+
+export const TimelinePlugin: DevtoolsPlugin = {
+  id: "timeline",
+  label: "Timeline",
+  component: TimelineTab,
+};

package/src/plugins/timeline/timeline-tab.tsx

@@ -0,0 +1,101 @@
+import { EmptyState } from "@shared/empty-state";
+
+import { signal, onMount, onUnmount } from "@praxisjs/core";
+
+import { TimelineRow } from "./components/timeline-row";
+import { FILTERS, type Filter } from "./constants";
+
+import type { Registry } from "@core/registry";
+import type { TimelineEntry } from "@core/types";
+
+export function TimelineTab({ registry }: { registry: Registry }) {
+  const entries = signal<TimelineEntry[]>(registry.getTimeline());
+  const filter = signal<Filter>("all");
+  const paused = signal(false);
+
+  let handlers: Array<() => void> = [];
+  onMount(() => {
+    handlers = [
+      registry.bus.on("timeline:push", () => {
+        if (!paused()) entries.set(registry.getTimeline());
+      }),
+    ];
+  });
+
+  onUnmount(() => {
+    handlers.forEach((off) => {
+      off();
+    });
+  });
+
+  return (
+    <div class="flex flex-col h-full overflow-hidden">
+      <div class="flex items-center gap-[3px] px-2 py-2 border-b border-border bg-bg shrink-0 flex-wrap">
+        {FILTERS.map((f) => (
+          <button
+            key={f.value}
+            onClick={() => {
+              filter.set(f.value);
+            }}
+            class={() =>
+              filter() === f.value
+                ? "text-[11px] px-2 py-[3px] rounded cursor-pointer font-sans bg-soft text-accent font-semibold"
+                : "text-[11px] px-2 py-[3px] rounded cursor-pointer font-sans text-muted hover:text-text hover:bg-section transition-colors duration-150"
+            }
+          >
+            {f.label}
+          </button>
+        ))}
+
+        <div class="flex-1" />
+
+        <button
+          onClick={() => {
+            if (paused()) entries.set(registry.getTimeline());
+            paused.update((v) => !v);
+          }}
+          class={() =>
+            `text-[11px] px-2 py-[3px] rounded cursor-pointer font-sans border border-border transition-colors duration-150 ${
+              paused() ? "text-warn border-warn" : "text-muted hover:text-text"
+            }`
+          }
+        >
+          {() => (paused() ? "Resume" : "Pause")}
+        </button>
+
+        <button
+          onClick={() => {
+            entries.set([]);
+          }}
+          class="text-[11px] px-2 py-[3px] rounded cursor-pointer font-sans border border-border text-muted hover:text-text transition-colors duration-150"
+        >
+          Clear
+        </button>
+      </div>
+
+      <div class="flex-1 overflow-y-auto">
+        {() => {
+          const f = filter();
+          const filtered =
+            f === "all"
+              ? entries()
+              : entries().filter(
+                  (e) =>
+                    e.type === f ||
+                    (f === "component:mount" && e.type === "component:unmount"),
+                );
+
+          if (filtered.length === 0) {
+            return (
+              <EmptyState message="No events yet. Interact with your app to see the timeline." />
+            );
+          }
+
+          return [...filtered]
+            .reverse()
+            .map((e) => <TimelineRow key={e.id} entry={e} />);
+        }}
+      </div>
+    </div>
+  );
+}