@praxisjs/devtools 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@praxisjs/devtools",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@unocss/reset": "^66.6.2",
+    "@praxisjs/core": "0.1.0",
+    "@praxisjs/jsx": "0.1.0",
+    "@praxisjs/runtime": "0.1.0",
+    "@praxisjs/shared": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@unocss/cli": "^66.6.2",
+    "@unocss/preset-wind3": "^66.6.2",
+    "typescript": "^5.9.3",
+    "unocss": "^66.6.2",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "scripts": {
+    "generate:css": "unocss \"src/**/*.{ts,tsx}\" -o assets/uno.generated.css",
+    "build": "vite build",
+    "prebuild": "pnpm run generate:css",
+    "dev": "vite build --watch"
+  }
+}

package/src/core/event-bus.ts

@@ -0,0 +1,19 @@
+type Handler<T = unknown> = (payload: T) => void;
+
+export class EventBus {
+  private readonly handlers = new Map<string, Set<Handler>>();
+
+  on<T = unknown>(event: string, handler: Handler<T>): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    (this.handlers.get(event) as Set<Handler>).add(handler as Handler);
+    return () => this.handlers.get(event)?.delete(handler as Handler);
+  }
+
+  emit(event: string, payload: unknown): void {
+    this.handlers.get(event)?.forEach((h) => {
+      h(payload);
+    });
+  }
+}

package/src/core/registry.ts

@@ -0,0 +1,219 @@
+import { EventBus } from "./event-bus";
+
+import type {
+  ComponentEntry,
+  LifecycleEvent,
+  SignalEntry,
+  TimelineEntry,
+  TimelineEventType,
+} from "./types";
+
+const MAX_HISTORY = 20;
+const MAX_TIMELINE = 200;
+
+let idCounter = 0;
+function uid(): string {
+  return `v${(++idCounter).toString()}_${Date.now().toString(36)}`;
+}
+
+export class Registry {
+  private static _instance: Registry | null = null;
+
+  static get instance(): Registry {
+    Registry._instance ??= new Registry();
+    return Registry._instance;
+  }
+
+  readonly bus = new EventBus();
+
+  private readonly instanceIds = new WeakMap<object, string>();
+  private readonly signals = new Map<string, SignalEntry>();
+  private readonly components = new Map<string, ComponentEntry>();
+  private readonly timeline: TimelineEntry[] = [];
+
+  private getInstanceId(instance: object): string {
+    if (!this.instanceIds.has(instance)) {
+      this.instanceIds.set(instance, uid());
+    }
+    return this.instanceIds.get(instance) as string;
+  }
+
+  registerSignal(
+    instance: object,
+    key: string,
+    value: unknown,
+    componentName: string,
+  ): void {
+    const componentId = this.getInstanceId(instance);
+    const id = `${componentId}:${key}`;
+
+    const entry: SignalEntry = {
+      id,
+      label: key,
+      componentId,
+      componentName,
+      value,
+      history: [{ value, timestamp: Date.now() }],
+      changedAt: Date.now(),
+    };
+
+    this.signals.set(id, entry);
+    this.bus.emit("signal:registered", entry);
+  }
+
+  updateSignal(
+    instance: object,
+    key: string,
+    newValue: unknown,
+    oldValue: unknown,
+  ): void {
+    const componentId = this.getInstanceId(instance);
+    const id = `${componentId}:${key}`;
+
+    const entry = this.signals.get(id);
+    if (!entry) return;
+
+    const history = [
+      ...entry.history,
+      { value: newValue, timestamp: Date.now() },
+    ].slice(-MAX_HISTORY);
+
+    const updated: SignalEntry = {
+      ...entry,
+      value: newValue,
+      history,
+      changedAt: Date.now(),
+    };
+
+    this.signals.set(id, updated);
+    this.bus.emit("signal:changed", { entry: updated, oldValue });
+    this.pushTimeline({
+      type: "signal:change",
+      label: `${entry.componentName}.${key}`,
+      data: { old: oldValue, new: newValue, signalId: id },
+    });
+  }
+
+  registerComponent(instance: object, name: string): void {
+    const id = this.getInstanceId(instance);
+
+    const entry: ComponentEntry = {
+      id,
+      name,
+      renderCount: 0,
+      lastRenderDuration: 0,
+      mountedAt: Date.now(),
+      status: "mounted",
+      lifecycle: [],
+    };
+
+    this.components.set(id, entry);
+    this.bus.emit("component:registered", entry);
+  }
+
+  recordRender(instance: object, duration: number): void {
+    const id = this.getInstanceId(instance);
+    const entry = this.components.get(id);
+    if (!entry) return;
+
+    entry.renderCount++;
+    entry.lastRenderDuration = duration;
+
+    this.bus.emit("component:render", { ...entry });
+    this.pushTimeline({
+      type: "component:render",
+      label: `<${entry.name}>`,
+      data: {
+        componentId: id,
+        duration: +duration.toFixed(3),
+        renderCount: entry.renderCount,
+      },
+    });
+  }
+
+  recordLifecycle(instance: object, hook: string): void {
+    const id = this.getInstanceId(instance);
+    const entry = this.components.get(id);
+    if (!entry) return;
+
+    const event: LifecycleEvent = { hook, timestamp: Date.now() };
+    entry.lifecycle.push(event);
+
+    this.bus.emit("lifecycle", { componentId: id, name: entry.name, hook });
+
+    const type: TimelineEventType =
+      hook === "onUnmount"
+        ? "component:unmount"
+        : hook === "onBeforeMount"
+          ? "component:mount"
+          : "lifecycle";
+
+    this.pushTimeline({
+      type,
+      label: `<${entry.name}>.${hook}`,
+      data: { componentId: id, hook },
+    });
+
+    if (hook === "onUnmount") {
+      entry.status = "unmounted";
+      this.bus.emit("component:unmount", { ...entry });
+      this.components.delete(id);
+      for (const [sid, s] of this.signals) {
+        if (s.componentId === id) this.signals.delete(sid);
+      }
+    }
+  }
+
+  recordMethodCall(
+    instance: object,
+    method: string,
+    args: unknown[],
+    result: unknown,
+    duration: number,
+    componentName: string,
+  ): void {
+    const componentId = this.getInstanceId(instance);
+    this.pushTimeline({
+      type: "method:call",
+      label: `${componentName}.${method}()`,
+      data: {
+        componentId,
+        args,
+        result,
+        duration: +duration.toFixed(3),
+      },
+    });
+  }
+
+  getSignals(): SignalEntry[] {
+    return [...this.signals.values()];
+  }
+
+  getComponents(): ComponentEntry[] {
+    return [...this.components.values()];
+  }
+
+  getTimeline(): TimelineEntry[] {
+    return [...this.timeline];
+  }
+
+  getSignalsByComponent(componentId: string): SignalEntry[] {
+    return this.getSignals().filter((s) => s.componentId === componentId);
+  }
+
+  private pushTimeline(data: Omit<TimelineEntry, "id" | "timestamp">): void {
+    const entry: TimelineEntry = {
+      id: uid(),
+      timestamp: Date.now(),
+      ...data,
+    };
+
+    this.timeline.push(entry);
+
+    if (this.timeline.length > MAX_TIMELINE) {
+      this.timeline.shift();
+    }
+
+    this.bus.emit("timeline:push", entry);
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,45 @@
+export interface HistoryEntry {
+  value: unknown;
+  timestamp: number;
+}
+
+export interface SignalEntry {
+  id: string;
+  label: string;
+  componentId: string;
+  componentName: string;
+  value: unknown;
+  history: HistoryEntry[];
+  changedAt: number;
+}
+
+export interface LifecycleEvent {
+  hook: string;
+  timestamp: number;
+}
+
+export interface ComponentEntry {
+  id: string;
+  name: string;
+  renderCount: number;
+  lastRenderDuration: number;
+  mountedAt: number;
+  status: 'mounted' | 'unmounted';
+  lifecycle: LifecycleEvent[];
+}
+
+export type TimelineEventType =
+  | 'signal:change'
+  | 'component:render'
+  | 'component:mount'
+  | 'component:unmount'
+  | 'lifecycle'
+  | 'method:call';
+
+export interface TimelineEntry {
+  id: string;
+  type: TimelineEventType;
+  label: string;
+  timestamp: number;
+  data: Record<string, unknown>;
+}

package/src/decorators/debug.ts

@@ -0,0 +1,161 @@
+import { Registry } from "../core/registry";
+
+export interface DebugOptions {
+  label?: string;
+}
+
+// Duck-type check: callable with .subscribe but no .set → Computed
+interface TrackedComputed {
+  (): unknown;
+  subscribe: (fn: (value: unknown) => void) => () => void;
+}
+
+function isComputed(value: unknown): value is TrackedComputed {
+  return (
+    typeof value === "function" &&
+    typeof (value as unknown as Record<string, unknown>).subscribe ===
+      "function" &&
+    !("set" in (value as object))
+  );
+}
+
+interface ComputedSlot {
+  computed: TrackedComputed;
+  unsub: () => void;
+}
+
+/**
+ * Tracks state, computed values, and methods in the devtools panel.
+ *
+ * On @State() properties (stacked):
+ *   @Debug()
+ *   @State() count = 0;
+ *
+ * On computed class fields:
+ *   @Debug()
+ *   doubled = computed(() => this.count * 2);
+ *
+ * On methods:
+ *   @Debug()
+ *   increment() { ... }
+ */
+export function Debug(options: DebugOptions = {}) {
+  return function (
+    target: object,
+    key: string,
+    descriptor?: PropertyDescriptor,
+  ): void {
+    const componentName = (target.constructor as { name: string }).name;
+    const label = options.label ?? key;
+
+    // ── Method decorator ─────────────────────────────────────────────────
+    if (descriptor && typeof descriptor.value === "function") {
+      const original = descriptor.value as (...args: unknown[]) => unknown;
+
+      descriptor.value = function (this: object, ...args: unknown[]) {
+        const start = performance.now();
+        let result: unknown;
+        let threw = false;
+
+        try {
+          result = original.apply(this, args);
+        } catch (err) {
+          threw = true;
+          result = err;
+          throw err;
+        } finally {
+          const duration = performance.now() - start;
+          Registry.instance.recordMethodCall(
+            this,
+            label,
+            args,
+            threw ? `throw ${String(result)}` : result,
+            duration,
+            componentName,
+          );
+        }
+
+        return result;
+      };
+
+      return;
+    }
+
+    const existingDesc = Object.getOwnPropertyDescriptor(target, key);
+
+    // ── Property decorator (wrapping @State()) ───────────────────────────
+    if (existingDesc?.get && existingDesc.set) {
+      const originalGet = existingDesc.get.bind(existingDesc);
+      const originalSet = existingDesc.set.bind(existingDesc);
+      const initialized = new WeakSet();
+
+      Object.defineProperty(target, key, {
+        get(this: object) {
+          return originalGet.call(this) as unknown;
+        },
+        set(this: object, newValue: unknown) {
+          if (!initialized.has(this)) {
+            initialized.add(this);
+            originalSet.call(this, newValue);
+            Registry.instance.registerSignal(
+              this,
+              label,
+              newValue,
+              componentName,
+            );
+          } else {
+            const oldValue: unknown = originalGet.call(this);
+            originalSet.call(this, newValue);
+            Registry.instance.updateSignal(this, label, newValue, oldValue);
+          }
+        },
+        enumerable: true,
+        configurable: true,
+      });
+
+      return;
+    }
+
+    // ── Computed class field ──────────────────────────────────────────────
+    // No existing descriptor means it's a plain class field (e.g. `doubled = computed(...)`).
+    // Intercept the assignment so we can subscribe to the computed's value changes.
+    const slots = new WeakMap<object, ComputedSlot>();
+
+    Object.defineProperty(target, key, {
+      get(this: object) {
+        return slots.get(this)?.computed;
+      },
+      set(this: object, value: unknown) {
+        // Clean up previous subscription on re-assignment
+        slots.get(this)?.unsub();
+
+        if (!isComputed(value)) {
+          console.warn(
+            `[PraxisJS DevTools] @Debug() on "${componentName}.${key}": ` +
+              `expected a computed() value but got ${typeof value}. Skipping.`,
+          );
+          return;
+        }
+
+        // subscribe() calls the callback immediately (synchronously), so we
+        // use a flag to skip the first call and register via registerSignal instead.
+        let skipFirst = true;
+        let prevValue = value();
+
+        const unsub = value.subscribe((newValue) => {
+          if (skipFirst) {
+            skipFirst = false;
+            return;
+          }
+          Registry.instance.updateSignal(this, label, newValue, prevValue);
+          prevValue = newValue;
+        });
+
+        slots.set(this, { computed: value, unsub });
+        Registry.instance.registerSignal(this, label, prevValue, componentName);
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  };
+}

package/src/decorators/index.ts

@@ -0,0 +1,3 @@
+export { Debug } from './debug';
+export type { DebugOptions } from './debug';
+export { Trace } from './trace';

package/src/decorators/trace.ts

@@ -0,0 +1,64 @@
+import { Registry } from '../core/registry';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyConstructor = new (...args: any[]) => any;
+
+/**
+ * Instruments a component class to report renders and lifecycle events
+ * to the devtools panel.
+ *
+ * @Trace()
+ * @Component()
+ * class MyComponent extends BaseComponent { ... }
+ */
+export function Trace() {
+  return function <T extends AnyConstructor>(constructor: T): T {
+    const name = constructor.name;
+    const registry = Registry.instance;
+    const proto = constructor.prototype as Record<string, unknown>;
+
+    // ── render() ──────────────────────────────────────────────────────────
+    const originalRender = proto.render as ((...args: unknown[]) => unknown) | undefined;
+
+    if (originalRender) {
+      proto.render = function (this: object, ...args: unknown[]) {
+        const start = performance.now();
+        const result = originalRender.call(this, ...args);
+        const duration = performance.now() - start;
+        registry.recordRender(this, duration);
+        return result;
+      };
+    }
+
+    // ── onBeforeMount – register the component instance ───────────────────
+    const originalOnBeforeMount = proto.onBeforeMount as
+      | ((...args: unknown[]) => unknown)
+      | undefined;
+
+    proto.onBeforeMount = function (this: object, ...args: unknown[]) {
+      registry.registerComponent(this, name);
+      registry.recordLifecycle(this, 'onBeforeMount');
+      return originalOnBeforeMount?.call(this, ...args);
+    };
+
+    // ── remaining lifecycle hooks ─────────────────────────────────────────
+    const hooks = [
+      'onMount',
+      'onUnmount',
+      'onBeforeUpdate',
+      'onUpdate',
+      'onAfterUpdate',
+    ] as const;
+
+    for (const hook of hooks) {
+      const original = proto[hook] as ((...args: unknown[]) => unknown) | undefined;
+
+      proto[hook] = function (this: object, ...args: unknown[]) {
+        registry.recordLifecycle(this, hook);
+        return original?.call(this, ...args);
+      };
+    }
+
+    return constructor;
+  };
+}

package/src/icons/ellipsis-vertical.tsx

@@ -0,0 +1,20 @@
+export function EllipsisVerticalIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class="lucide lucide-ellipsis-vertical-icon lucide-ellipsis-vertical"
+    >
+      <circle cx="12" cy="12" r="1" />
+      <circle cx="12" cy="5" r="1" />
+      <circle cx="12" cy="19" r="1" />
+    </svg>
+  );
+}

package/src/icons/index.ts

@@ -0,0 +1,6 @@
+export { EllipsisVerticalIcon } from "./ellipsis-vertical";
+export { PanelBottomIcon } from "./panel-bottom";
+export { PanelLeftIcon } from "./panel-left";
+export { PanelRightIcon } from "./panel-right";
+export { PanelTopIcon } from "./panel-top";
+export { XIcon } from "./x";

package/src/icons/panel-bottom.tsx

@@ -0,0 +1,19 @@
+export function PanelBottomIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class="lucide lucide-panel-bottom-icon lucide-panel-bottom"
+    >
+      <rect width="18" height="18" x="3" y="3" rx="2" />
+      <path d="M3 15h18" />
+    </svg>
+  );
+}

package/src/icons/panel-left.tsx

@@ -0,0 +1,19 @@
+export function PanelLeftIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class="lucide lucide-panel-left-icon lucide-panel-left"
+    >
+      <rect width="18" height="18" x="3" y="3" rx="2" />
+      <path d="M9 3v18" />
+    </svg>
+  );
+}

package/src/icons/panel-right.tsx

@@ -0,0 +1,19 @@
+export function PanelRightIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class="lucide lucide-panel-right-icon lucide-panel-right"
+    >
+      <rect width="18" height="18" x="3" y="3" rx="2" />
+      <path d="M15 3v18" />
+    </svg>
+  );
+}

package/src/icons/panel-top.tsx

@@ -0,0 +1,19 @@
+export function PanelTopIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class="lucide lucide-panel-top-icon lucide-panel-top"
+    >
+      <rect width="18" height="18" x="3" y="3" rx="2" />
+      <path d="M3 9h18" />
+    </svg>
+  );
+}

package/src/icons/x.tsx

@@ -0,0 +1,19 @@
+export function XIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class="lucide lucide-x-icon lucide-x"
+    >
+      <path d="M18 6 6 18" />
+      <path d="m6 6 12 12" />
+    </svg>
+  );
+}