@praxisjs/devtools 0.2.34 → 0.3.1

package/src/decorators/debug.ts

@@ -1,4 +1,4 @@
-import { computed } from "@praxisjs/core/internal";
+import { computed, effect, untrack } from "@praxisjs/core/internal";
 import {
   createMethodDecorator,
   createGetterObserverDecorator,
@@ -8,8 +8,23 @@ import {
 
 import { Registry } from "../core/registry";
 
+// Read inline (not through a helper): bundlers replace process.env.NODE_ENV at build time, and only a
+// literal check lets them drop the instrumentation, and the registry it uses, from production builds.
+declare const process: { env: { NODE_ENV?: string } };
+
 export interface DebugOptions {
+  /** Name shown in the panel. Defaults to the member name. */
   label?: string;
+  /**
+   * Also logs every change (fields, getters) or call (methods) to the console. `"trace"` logs with
+   * a stack trace, which shows what caused it.
+   */
+  log?: boolean | "trace";
+  /**
+   * Pauses in the debugger on a change or call. A function decides per change: it receives the new
+   * and the previous value (for methods, the arguments and `undefined`).
+   */
+  break?: boolean | ((next: unknown, prev: unknown) => boolean);
 }
 
 // Duck-type check: callable with .subscribe but no .set → Computed
@@ -37,11 +52,48 @@ interface DebugDecorator {
   (value: undefined, context: ClassFieldDecoratorContext): void;
 }
 
+function componentNameOf(instance: object): string {
+  return (instance.constructor as { name: string }).name;
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+/** Console logging and debugger pauses requested through the options. */
+function makeReporter(options: DebugOptions) {
+  const { log, break: pause } = options;
+  if (!log && !pause) return null;
+  return (what: string, next: unknown, prev: unknown): void => {
+    untrack(() => {
+      if (log === "trace") console.trace(`[PraxisJS] ${what}`, next, prev);
+      else if (log) console.log(`[PraxisJS] ${what}`, next, prev);
+      if (pause === true || (typeof pause === "function" && pause(next, prev))) {
+        debugger;
+      }
+    });
+  };
+}
+
 /**
- * Tracks state, computed values, and methods in the devtools panel.
- * Supports @State() fields, @Computed() getters, and methods.
+ * Tracks state, props, computed values and methods in the devtools panel.
+ *
+ * - Fields with an accessor (`@State`, `@Prop`, `@Persisted`, …) are observed reactively, so a
+ *   change is reported whatever caused it, including a parent passing a new prop.
+ * - Fields holding a `computed()` report each new value.
+ * - `@Computed()` getters report each new value.
+ * - Methods report every call with its arguments, result and duration; for a method that returns a
+ *   promise, when the promise settles.
  */
 export function Debug(options: DebugOptions = {}): DebugDecorator {
+  // Production builds keep the member exactly as declared: no wrapper, no observation.
+  if (process.env.NODE_ENV === "production") return (() => undefined) as DebugDecorator;
+  const report = makeReporter(options);
+
   const impl = function (
     value: unknown,
     context:
@@ -56,23 +108,28 @@ export function Debug(options: DebugOptions = {}): DebugDecorator {
       createMethodDecorator({
         wrap(_original, _instance, _name) {
           return function (this: object, ...args: unknown[]) {
-            const componentName = (this.constructor as { name: string }).name;
+            const componentName = componentNameOf(this);
+            report?.(`${componentName}.${label}()`, args, undefined);
             const start = performance.now();
+            const record = (result: unknown): void => {
+              Registry.instance.recordMethodCall(
+                this, label, args, result, performance.now() - start, componentName,
+              );
+            };
             let result: unknown;
-            let threw = false;
             try {
               result = original.apply(this, args);
             } catch (err) {
-              threw = true;
-              result = err;
+              record(`throw ${String(err)}`);
               throw err;
-            } finally {
-              const duration = performance.now() - start;
-              Registry.instance.recordMethodCall(
-                this, label, args,
-                threw ? `throw ${String(result)}` : result,
-                duration, componentName,
+            }
+            if (isThenable(result)) {
+              result.then(
+                (resolved) => { record(resolved); },
+                (err: unknown) => { record(`reject ${String(err)}`); },
               );
+            } else {
+              record(result);
             }
             return result;
           };
@@ -85,7 +142,7 @@ export function Debug(options: DebugOptions = {}): DebugDecorator {
       const originalGetter = value as (this: object) => unknown;
       createGetterObserverDecorator({
         observe(getter, instance, _name) {
-          const componentName = (instance.constructor as { name: string }).name;
+          const componentName = componentNameOf(instance);
           // Defer so field initializers (e.g. @State()) have run before we read them.
           queueMicrotask(() => {
             const c = computed(() => getter.call(instance));
@@ -95,6 +152,7 @@ export function Debug(options: DebugOptions = {}): DebugDecorator {
             c.subscribe((newValue) => {
               if (skipFirst) { skipFirst = false; return; }
               Registry.instance.updateSignal(instance, label, newValue, prevValue);
+              report?.(`${componentName}.${label}`, newValue, prevValue);
               prevValue = newValue;
             });
           });
@@ -105,26 +163,30 @@ export function Debug(options: DebugOptions = {}): DebugDecorator {
 
     createFieldDecorator({
       bind(instance, name, _initialValue): FieldBinding {
-        const componentName = (instance.constructor as { name: string }).name;
+        const componentName = componentNameOf(instance);
 
-        // @State() runs inner-first, so its getter/setter is already on the instance.
+        // @State(), @Prop() and friends run inner-first, so their accessor is already on the
+        // instance. Reading it in an effect reports every change, whoever made it.
         const existingDesc = Object.getOwnPropertyDescriptor(instance, name);
-        if (existingDesc?.get && existingDesc.set) {
-          // eslint-disable-next-line @typescript-eslint/unbound-method
-          const originalGet = existingDesc.get;
-          // eslint-disable-next-line @typescript-eslint/unbound-method
-          const originalSet = existingDesc.set;
-          Registry.instance.registerSignal(instance, label, originalGet.call(instance), componentName);
-          return {
-            descriptor: {
-              get(this: object) { return originalGet.call(this) as unknown; },
-              set(this: object, newValue: unknown) {
-                const oldValue: unknown = originalGet.call(this);
-                originalSet.call(this, newValue);
-                Registry.instance.updateSignal(this, label, newValue, oldValue);
-              },
-            },
-          };
+        if (existingDesc?.get !== undefined) {
+          const read = (): unknown => (instance as unknown as Record<string, unknown>)[name];
+          let prev: unknown;
+          let first = true;
+          const stop = effect(() => {
+            const next = read();
+            if (first) {
+              first = false;
+              prev = next;
+              untrack(() => { Registry.instance.registerSignal(instance, label, next, componentName); });
+              return;
+            }
+            if (Object.is(next, prev)) return;
+            const old = prev;
+            prev = next;
+            untrack(() => { Registry.instance.updateSignal(instance, label, next, old); });
+            report?.(`${componentName}.${label}`, next, old);
+          });
+          return { onUnmount: stop };
         }
 
         const initialValue = _initialValue;
@@ -148,6 +210,7 @@ export function Debug(options: DebugOptions = {}): DebugDecorator {
           const unsub = comp.subscribe((newValue) => {
             if (skipFirst) { skipFirst = false; return; }
             Registry.instance.updateSignal(instance, label, newValue, prevValue);
+            report?.(`${componentName}.${label}`, newValue, prevValue);
             prevValue = newValue;
           });
           Registry.instance.registerSignal(instance, label, prevValue, componentName);
@@ -171,6 +234,7 @@ export function Debug(options: DebugOptions = {}): DebugDecorator {
               slot = { computed: newValue, unsub: subscribe(newValue) };
             },
           },
+          onUnmount() { slot.unsub(); },
         };
       },
     })(undefined, context);

package/src/decorators/index.ts

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

package/src/decorators/trace.ts

@@ -7,6 +7,10 @@ import {
 
 import { Registry } from "../core/registry";
 
+// Read inline (not through a helper): bundlers replace process.env.NODE_ENV at build time, and only a
+// literal check lets them drop the instrumentation, and the registry it uses, from production builds.
+declare const process: { env: { NODE_ENV?: string } };
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyConstructor = new (...args: any[]) => any;
 
@@ -16,13 +20,23 @@ const EXTRA_HOOKS = ["onBeforeUpdate", "onUpdate", "onAfterUpdate"] as const;
  * Instruments a component class to report renders and lifecycle events
  * to the devtools panel.
  *
- * @Trace()
+ * @Trace({ slow: 4 })   // also warn when a render takes more than 4 ms
  * @Component()
  * class MyComponent extends StatefulComponent { ... }
  */
+export interface TraceOptions {
+  /** Warns in the console when a render of this component takes longer than this many ms. */
+  slow?: number;
+}
+
 class TraceBehavior extends ClassBehavior {
+  constructor(private readonly slow: number | undefined) {
+    super();
+  }
+
   create(instance: RootComponent): ClassEnhancement {
     const registry = Registry.instance;
+    const slow = this.slow;
 
     return {
       onMount() {
@@ -36,6 +50,11 @@ class TraceBehavior extends ClassBehavior {
         const result = originalRender();
         const duration = performance.now() - start;
         registry.recordRender(instance, duration);
+        if (slow !== undefined && duration > slow) {
+          console.warn(
+            `[PraxisJS DevTools] <${instance.constructor.name}> rendered in ${duration.toFixed(1)} ms (over ${String(slow)} ms).`,
+          );
+        }
         return result;
       },
     };
@@ -64,8 +83,12 @@ class TraceBehavior extends ClassBehavior {
   }
 }
 
-const traceBehavior = new TraceBehavior();
+// Created on first use: a module-level instance would keep this class and the registry in
+// production bundles, where @Trace() does nothing.
+let defaultBehavior: TraceBehavior | undefined;
 
-export function Trace() {
-  return createClassDecorator(traceBehavior);
+export function Trace(options: TraceOptions = {}) {
+  // Production builds keep the class exactly as declared.
+  if (process.env.NODE_ENV === "production") return <T>(constructor: T, _context: ClassDecoratorContext): T => constructor;
+  return createClassDecorator(options.slow === undefined ? (defaultBehavior ??= new TraceBehavior(undefined)) : new TraceBehavior(options.slow));
 }

package/src/index.ts

@@ -3,6 +3,7 @@ export type { DevToolsOptions } from "@/ui/dev-tools";
 
 export { Debug, Trace } from "@/decorators";
 export type { DebugOptions } from "@/decorators/debug";
+export type { TraceOptions } from "@/decorators/trace";
 
 export { Registry } from "@/core/registry";
 export type {
@@ -18,3 +19,7 @@ export type { DevtoolsPlugin } from "@/plugins/types";
 export { SignalsPlugin } from "@/plugins/signals";
 export { ComponentsPlugin } from "@/plugins/components";
 export { TimelinePlugin } from "@/plugins/timeline";
+export { PerformancePlugin } from "@/plugins/performance";
+
+export { Profiler } from "@/core/profiler";
+export type { ProfileSnapshot, OwnerStats } from "@/core/profiler";

package/src/plugins/performance/index.ts

@@ -0,0 +1,9 @@
+import { PerformanceTab } from "./performance-tab";
+
+import type { DevtoolsPlugin } from "@plugins/types";
+
+export const PerformancePlugin: DevtoolsPlugin = {
+  id: "performance",
+  label: "Performance",
+  component: PerformanceTab,
+};

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

@@ -0,0 +1,111 @@
+import { EmptyState } from "@shared/empty-state";
+
+import { StatefulComponent } from "@praxisjs/core";
+import { Component, Prop, State } from "@praxisjs/decorators";
+import { For } from "@praxisjs/runtime";
+
+import type { ProfileSnapshot } from "@core/profiler";
+import type { Registry } from "@core/registry";
+
+const BUTTON =
+  "text-[11px] px-2 py-[3px] rounded cursor-pointer font-sans border border-border text-muted hover:text-text transition-colors duration-150";
+
+function ms(value: number): string {
+  return `${value.toFixed(value < 10 ? 2 : 1)} ms`;
+}
+
+@Component()
+export class PerformanceTab extends StatefulComponent {
+  @State() snapshot: ProfileSnapshot | null = null;
+  @Prop() registry!: Registry;
+
+  private _off: (() => void) | null = null;
+
+  onMount() {
+    const { profiler } = this.registry;
+    this.refresh();
+    this._off = profiler.bus.on("profile:changed", () => { this.refresh(); });
+  }
+
+  onUnmount() {
+    this._off?.();
+  }
+
+  // The panel's own updates are kept out of the recording.
+  refresh() {
+    const { profiler } = this.registry;
+    profiler.muted(() => { this.snapshot = profiler.snapshot(); });
+  }
+
+  render() {
+    const { profiler } = this.registry;
+    return (
+      <div class="flex flex-col h-full overflow-hidden">
+        <div class="flex items-center gap-[6px] px-2 py-2 border-b border-border bg-bg shrink-0">
+          <button
+            class={() => `${BUTTON} ${this.snapshot?.recording ? "text-warn border-warn" : ""}`}
+            onClick={() => {
+              if (profiler.isRecording) profiler.stop();
+              else profiler.start();
+            }}
+          >
+            {() => (this.snapshot?.recording ? "Stop" : "Record")}
+          </button>
+          <button class={BUTTON} onClick={() => { profiler.reset(); }}>
+            Reset
+          </button>
+          <div class="flex-1" />
+          <span class="text-[10px] text-subtle font-mono">
+            {() => (this.snapshot ? `${(this.snapshot.duration / 1000).toFixed(1)} s` : "")}
+          </span>
+        </div>
+
+        <div class="grid grid-cols-4 gap-px bg-border border-b border-border shrink-0">
+          {() => {
+            const s = this.snapshot;
+            const cells: Array<[string, string]> = s
+              ? [
+                  ["Writes", String(s.writes)],
+                  ["Effect runs", String(s.effectRuns)],
+                  ["Effect time", ms(s.effectMs)],
+                  ["Computed runs", `${String(s.computeRuns)} · ${ms(s.computeMs)}`],
+                ]
+              : [];
+            return cells.map(([label, value]) => (
+              <div class="bg-bg px-3 py-2">
+                <div class="text-[9px] text-subtle font-bold tracking-[0.12em] uppercase">{label}</div>
+                <div class="text-[13px] text-text font-mono">{value}</div>
+              </div>
+            ));
+          }}
+        </div>
+
+        <div class="grid grid-cols-[1.4fr_0.6fr_0.8fr_0.8fr] 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>Component</span>
+          <span>Runs</span>
+          <span>Time</span>
+          <span>Slowest</span>
+        </div>
+
+        <div class="flex-1 overflow-y-auto">
+          <For
+            each={() => this.snapshot?.owners ?? []}
+            by="name"
+            fallback={
+              <EmptyState message="Press Record, use your app, then Stop. Bindings and effects are grouped by the component that created them." />
+            }
+          >
+            {(owner) => (
+              <div class="grid grid-cols-[1.4fr_0.6fr_0.8fr_0.8fr] items-center px-3 h-7 text-[11px] border-b border-border gap-2 font-mono">
+                <span class="text-accent truncate">{() => owner().name}</span>
+                <span class="text-text">{() => String(owner().effectRuns)}</span>
+                <span class="text-text">{() => ms(owner().effectMs)}</span>
+                <span class="text-muted">{() => ms(owner().maxMs)}</span>
+              </div>
+            )}
+          </For>
+        </div>
+      </div>
+    );
+  }
+}

package/src/ui/dev-tools.tsx

@@ -2,6 +2,7 @@ import logo from "@assets/logo.svg";
 import unoStyles from "@assets/uno.generated.css?inline";
 import { Registry } from "@core/registry";
 import { ComponentsPlugin } from "@plugins/components";
+import { PerformancePlugin } from "@plugins/performance";
 import { SignalsPlugin } from "@plugins/signals";
 import { TimelinePlugin } from "@plugins/timeline";
 import unoReset from "@unocss/reset/tailwind-v4.css?inline";
@@ -18,6 +19,7 @@ const DEFAULT_PLUGINS: DevtoolsPlugin[] = [
   SignalsPlugin,
   ComponentsPlugin,
   TimelinePlugin,
+  PerformancePlugin,
 ];
 
 export interface DevToolsOptions {
@@ -75,6 +77,9 @@ export const DevTools = {
 
     this.plugins.forEach((p) => p.setup?.(Registry.instance));
 
+    // Reachable from the browser console: __PRAXIS_DEVTOOLS__.profiler.start(), .getSignals(), …
+    (globalThis as { __PRAXIS_DEVTOOLS__?: Registry }).__PRAXIS_DEVTOOLS__ = Registry.instance;
+
     const host = document.createElement("div");
     host.id = "praxisjs-devtools";
     document.body.appendChild(host);