@alloy-js/core 0.23.0-dev.9 → 0.23.1

package/src/devtools/devtools-server.ts

@@ -5,6 +5,15 @@
  * messages, and reset. Transport details (HTTP/WebSocket) are delegated
  * to devtools-transport.ts.
  */
+import type { ChangeChannel, ChangeEvent } from "../debug/trace-writer.js";
+import {
+  ALL_CHANNELS,
+  closeTrace,
+  initTrace,
+  isTraceEnabled,
+  queryChannel,
+  setChangeListener,
+} from "../debug/trace-writer.js";
 import {
   createTransport,
   getAlloyVersion,
@@ -15,11 +24,6 @@ import {
 // Public types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export interface DevtoolsMessage {
-  type: string;
-  [key: string]: unknown;
-}
-
 export interface DevtoolsIncomingMessage {
   type: string;
   [key: string]: unknown;
@@ -47,6 +51,95 @@ let devtoolsInitialized = false;
 let loggedDevtoolsLinks = false;
 let waitingForConnection = false;
 let configuredPort: number | undefined;
+let tempDbPath: string | null = null;
+let subscribedPromise: Promise<void> | null = null;
+let resolveSubscribed: (() => void) | null = null;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-client subscription state
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface ClientState {
+  subscriptions: Set<ChangeChannel>;
+}
+
+const clientStates = new Map<any, ClientState>();
+
+function eventToMessageType(event: ChangeEvent): string {
+  const map: Record<string, Record<string, string>> = {
+    render: {
+      added: "render:node_added",
+      updated: "render:node_updated",
+      removed: "render:node_removed",
+      reset: "render:reset",
+    },
+    effects: { added: "effect:added", updated: "effect:updated" },
+    refs: { added: "ref:added" },
+    edges: { added: `edge:${(event.data as any).edge_type ?? "track"}` },
+    symbols: {
+      added: "symbol:added",
+      updated: "symbol:updated",
+      removed: "symbol:removed",
+    },
+    scopes: {
+      added: "scope:added",
+      updated: "scope:updated",
+      removed: "scope:removed",
+    },
+    files: {
+      added: "file:added",
+      updated: "file:updated",
+      removed: "file:removed",
+    },
+    directories: { added: "directory:added", removed: "directory:removed" },
+    diagnostics: { added: "diagnostics:report" },
+    errors: { added: "render:error" },
+    lifecycle: { added: "effect:lifecycle" },
+    scheduler: { added: "scheduler:job" },
+  };
+  return (
+    map[event.channel]?.[event.action] ?? `${event.channel}:${event.action}`
+  );
+}
+
+function channelToInitialMessageType(
+  channel: ChangeChannel,
+  row: Record<string, unknown>,
+): string {
+  const map: Record<string, string> = {
+    render: "render:node_added",
+    effects: "effect:added",
+    refs: "ref:added",
+    symbols: "symbol:added",
+    scopes: "scope:added",
+    files: "file:added",
+    directories: "directory:added",
+    diagnostics: "diagnostics:report",
+    errors: "render:error",
+    lifecycle: "effect:lifecycle",
+    scheduler: "scheduler:job",
+  };
+  if (channel === "edges") {
+    return `edge:${(row.type as string) ?? "track"}`;
+  }
+  return map[channel] ?? `${channel}:added`;
+}
+
+function sendInitialState(socket: any, channels: ChangeChannel[]): void {
+  if (!isTraceEnabled()) return;
+  for (const channel of channels) {
+    const rows = queryChannel(channel);
+    for (const row of rows) {
+      const msgType = channelToInitialMessageType(channel, row);
+      // Remap SQLite column names that collide with the message `type` field
+      if (channel === "effects" && row.type !== undefined) {
+        row.effect_type = row.type;
+      }
+      const msg = { ...row, type: msgType };
+      socket.send(JSON.stringify(msg));
+    }
+  }
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Environment helpers
@@ -60,6 +153,19 @@ function isNodeEnvironment() {
   );
 }
 
+// Cached once at module load. Stable for production runs. Tests that modify
+// process.env.ALLOY_DEBUG dynamically must call refreshDebugState() afterward.
+let _envDebugEnabled: boolean =
+  isNodeEnvironment() && Boolean(process.env.ALLOY_DEBUG);
+
+/**
+ * Invalidates the cached env-var result for isDevtoolsEnabled(). Call this in
+ * test beforeEach hooks after modifying process.env.ALLOY_DEBUG.
+ */
+export function refreshDebugState(): void {
+  _envDebugEnabled = isNodeEnvironment() && Boolean(process.env.ALLOY_DEBUG);
+}
+
 function getCwd() {
   if (!isNodeEnvironment()) return undefined;
   try {
@@ -84,7 +190,7 @@ function resolveDebugPort() {
 /** Returns true when devtools are enabled (via env var or explicit call). */
 export function isDevtoolsEnabled() {
   if (!isNodeEnvironment()) return false;
-  return devtoolsExplicitlyEnabled || Boolean(process.env.ALLOY_DEBUG);
+  return devtoolsExplicitlyEnabled || _envDebugEnabled;
 }
 
 /** Returns true when a devtools client is currently connected. */
@@ -98,6 +204,38 @@ export function getDevtoolsServerInfo(): DevtoolsServerInfo | null {
   return { port: transportState.port, connected: transportState.connected };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Temp SQLite for devtools
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function ensureSqliteForDevtools(): Promise<void> {
+  if (isTraceEnabled()) return;
+  const os = await import("node:os");
+  const path = await import("node:path");
+  tempDbPath = path.join(os.tmpdir(), `alloy-debug-${process.pid}.db`);
+  await initTrace(tempDbPath);
+  process.on("exit", () => {
+    if (!tempDbPath) return;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const fs = require("node:fs");
+      fs.unlinkSync(tempDbPath);
+      try {
+        fs.unlinkSync(tempDbPath + "-wal");
+      } catch {
+        /* ignore */
+      }
+      try {
+        fs.unlinkSync(tempDbPath + "-shm");
+      } catch {
+        /* ignore */
+      }
+    } catch {
+      /* ignore cleanup failures */
+    }
+  });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Server lifecycle
 // ─────────────────────────────────────────────────────────────────────────────
@@ -108,6 +246,13 @@ async function ensureServer(): Promise<DevtoolsTransportState> {
     transportPromise = createTransport({
       port: configuredPort ?? resolveDebugPort(),
       onConnection(socket) {
+        // Start with no subscriptions — client must subscribe explicitly.
+        clientStates.set(socket, { subscriptions: new Set() });
+        if (!subscribedPromise) {
+          subscribedPromise = new Promise<void>((resolve) => {
+            resolveSubscribed = resolve;
+          });
+        }
         if (waitingForConnection) {
           waitingForConnection = false;
           process.stdout.write(" Connected!\n");
@@ -117,21 +262,75 @@ async function ensureServer(): Promise<DevtoolsTransportState> {
             type: "debugger:info",
             version: getAlloyVersion(),
             cwd: getCwd(),
+            sourceMapEnabled: process.execArgv.includes("--enable-source-maps"),
           }),
         );
       },
-      onMessage(raw) {
+      onMessage(raw, socket) {
         const message = raw as DevtoolsIncomingMessage;
         if (!message || !message.type) return;
+
+        if (message.type === "subscribe") {
+          const channels = (message as any).channels as string[];
+          const state = clientStates.get(socket);
+          if (state && channels && Array.isArray(channels)) {
+            const validChannels = channels.filter((ch) =>
+              ALL_CHANNELS.includes(ch as ChangeChannel),
+            ) as ChangeChannel[];
+            state.subscriptions = new Set(validChannels);
+            sendInitialState(socket, validChannels);
+          }
+          resolveSubscribed?.();
+          return;
+        }
+        if (message.type === "unsubscribe") {
+          const channels = (message as any).channels as string[];
+          const state = clientStates.get(socket);
+          if (state && channels) {
+            for (const ch of channels)
+              state.subscriptions.delete(ch as ChangeChannel);
+          }
+          return;
+        }
+
         for (const handler of messageHandlers) {
           handler(message);
         }
       },
-      onDisconnect() {
-        // Currently no-op; transport handles client set management
+      onDisconnect(socket) {
+        clientStates.delete(socket);
       },
     }).then((state) => {
       transportState = state;
+
+      // Wire up the change notification bus to forward events to subscribed clients
+      setChangeListener((event: ChangeEvent) => {
+        if (!transportState) return;
+
+        // Lifecycle signals are broadcast to ALL connected clients
+        const signalType = (event.data as any)?._signal as string | undefined;
+        if (signalType) {
+          const payload = JSON.stringify({ type: signalType });
+          for (const client of transportState.clients) {
+            if (client.readyState === client.OPEN) {
+              client.send(payload);
+            }
+          }
+          return;
+        }
+
+        const msgType = eventToMessageType(event);
+        const message = { ...event.data, type: msgType };
+        const payload = JSON.stringify(message);
+
+        for (const [client, clientState] of clientStates) {
+          if (client.readyState !== client.OPEN) continue;
+          if (clientState.subscriptions.has(event.channel)) {
+            client.send(payload);
+          }
+        }
+      });
+
       if (!loggedDevtoolsLinks) {
         loggedDevtoolsLinks = true;
         // eslint-disable-next-line no-console
@@ -173,8 +372,14 @@ async function ensureServer(): Promise<DevtoolsTransportState> {
 export async function waitForDevtoolsConnection(): Promise<void> {
   devtoolsExplicitlyEnabled = true;
   const server = await ensureServer();
-  if (server.connected) return;
-  await server.ready;
+  if (!server.connected) {
+    await server.ready;
+  }
+  // Wait for the client to send its initial subscribe message so that
+  // messages emitted during a synchronous render are not dropped.
+  if (subscribedPromise) {
+    await subscribedPromise;
+  }
 }
 
 /**
@@ -191,6 +396,7 @@ export async function enableDevtools(
   if (options?.port !== undefined) {
     configuredPort = options.port;
   }
+  await ensureSqliteForDevtools();
   const server = await ensureServer();
   return { port: server.port, connected: server.connected };
 }
@@ -203,6 +409,7 @@ export async function initDevtoolsIfEnabled(): Promise<void> {
   if (devtoolsInitialized) return;
   if (!isDevtoolsEnabled()) return;
   devtoolsInitialized = true;
+  await ensureSqliteForDevtools();
   await waitForDevtoolsConnection();
 }
 
@@ -232,28 +439,6 @@ export async function enableDevtoolsAndConnect(
 // Messaging
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** Broadcast a message to all connected devtools clients. */
-export function broadcastDevtoolsMessage(message: DevtoolsMessage) {
-  if (!isDevtoolsEnabled()) return;
-  if (!transportState) return;
-  if (transportState.clients.size === 0) return;
-
-  try {
-    const payload = JSON.stringify(message);
-    for (const client of transportState.clients) {
-      if (client.readyState === client.OPEN) {
-        client.send(payload);
-      }
-    }
-  } catch (err) {
-    // eslint-disable-next-line no-console
-    console.error(
-      `Failed to send devtools message (type: ${message.type}):`,
-      err,
-    );
-  }
-}
-
 /** Register a handler for incoming devtools messages. Returns an unsubscribe function. */
 export function registerDevtoolsMessageHandler(
   handler: (message: DevtoolsIncomingMessage) => void,
@@ -278,6 +463,8 @@ export function assertDevtoolsConnectedForSyncRender() {
 
 /** Reset all devtools state. For use in tests only. */
 export async function resetDevtoolsServerForTests() {
+  setChangeListener(null);
+  clientStates.clear();
   if (transportState) {
     await transportState.close();
   }
@@ -287,4 +474,10 @@ export async function resetDevtoolsServerForTests() {
   devtoolsInitialized = false;
   configuredPort = undefined;
   loggedDevtoolsLinks = false;
+  subscribedPromise = null;
+  resolveSubscribed = null;
+  // Re-read the env var in case tests modified process.env.ALLOY_DEBUG
+  refreshDebugState();
+  // Close the trace DB so each test starts fresh
+  closeTrace();
 }

package/src/devtools/devtools-transport.ts

@@ -58,8 +58,8 @@ function loadDevtoolsUiHtml(): string | null {
 export interface CreateTransportOptions {
   port: number;
   onConnection(socket: any): void;
-  onMessage(message: unknown): void;
-  onDisconnect(): void;
+  onMessage(message: unknown, socket: any): void;
+  onDisconnect(socket: any): void;
 }
 
 /**
@@ -137,7 +137,7 @@ export async function createTransport(
 
     socket.on("message", (data) => {
       try {
-        options.onMessage(JSON.parse(String(data)));
+        options.onMessage(JSON.parse(String(data)), socket);
       } catch {
         // ignore malformed messages
       }
@@ -146,7 +146,7 @@ export async function createTransport(
     socket.on("close", () => {
       clients.delete(socket);
       state.connected = clients.size > 0;
-      options.onDisconnect();
+      options.onDisconnect(socket);
     });
   });
 

package/src/devtools-entry.browser.ts

@@ -1,15 +1,13 @@
 export type {
-  BatchMessage,
+  // Individual server→client message types
   ClientToServerMessage,
   DebuggerInfoMessage,
-  DiagnosticInfo,
+  DiagnosticRow,
   DiagnosticsReportMessage,
   DirectoryAddedMessage,
   DirectoryRemovedMessage,
   EffectAddedMessage,
-  EffectEdgeInfo,
   EffectEdgeUpdatedMessage,
-  EffectInfo,
   EffectTrackMessage,
   EffectTriggerMessage,
   EffectUpdatedMessage,
@@ -18,27 +16,25 @@ export type {
   FileUpdatedMessage,
   FlushJobsCompleteMessage,
   RefAddedMessage,
-  RefInfo,
   RenderCompleteMessage,
   RenderErrorMessage,
-  RenderErrorStackEntry,
   RenderNodeAddedMessage,
   RenderNodeRemovedMessage,
   RenderNodeUpdatedMessage,
   RenderResetMessage,
-  RenderTreeNode,
+  // Individual client→server message types
   RerenderBreakRequestMessage,
   RerenderRequestMessage,
-  ScopeCreateMessage,
-  ScopeDeleteMessage,
-  ScopeInfo,
-  ScopeUpdateMessage,
+  ScopeAddedMessage,
+  ScopeRemovedMessage,
+  ScopeUpdatedMessage,
   ServerToClientMessage,
   SourceLocation,
-  SymbolCreateMessage,
-  SymbolDeleteMessage,
-  SymbolInfo,
-  SymbolUpdateMessage,
+  SubscribeMessage,
+  SymbolAddedMessage,
+  SymbolRemovedMessage,
+  SymbolUpdatedMessage,
+  UnsubscribeMessage,
 } from "./devtools/devtools-protocol.js";
 export {
   enableDevtools,

package/src/devtools-entry.ts

@@ -1,16 +1,13 @@
 export type {
   // Individual server→client message types
-  BatchMessage,
   ClientToServerMessage,
   DebuggerInfoMessage,
-  DiagnosticInfo,
+  DiagnosticRow,
   DiagnosticsReportMessage,
   DirectoryAddedMessage,
   DirectoryRemovedMessage,
   EffectAddedMessage,
-  EffectEdgeInfo,
   EffectEdgeUpdatedMessage,
-  EffectInfo,
   EffectTrackMessage,
   EffectTriggerMessage,
   EffectUpdatedMessage,
@@ -19,28 +16,25 @@ export type {
   FileUpdatedMessage,
   FlushJobsCompleteMessage,
   RefAddedMessage,
-  RefInfo,
   RenderCompleteMessage,
   RenderErrorMessage,
-  RenderErrorStackEntry,
   RenderNodeAddedMessage,
   RenderNodeRemovedMessage,
   RenderNodeUpdatedMessage,
   RenderResetMessage,
-  RenderTreeNode,
   // Individual client→server message types
   RerenderBreakRequestMessage,
   RerenderRequestMessage,
-  ScopeCreateMessage,
-  ScopeDeleteMessage,
-  ScopeInfo,
-  ScopeUpdateMessage,
+  ScopeAddedMessage,
+  ScopeRemovedMessage,
+  ScopeUpdatedMessage,
   ServerToClientMessage,
   SourceLocation,
-  SymbolCreateMessage,
-  SymbolDeleteMessage,
-  SymbolInfo,
-  SymbolUpdateMessage,
+  SubscribeMessage,
+  SymbolAddedMessage,
+  SymbolRemovedMessage,
+  SymbolUpdatedMessage,
+  UnsubscribeMessage,
 } from "./devtools/devtools-protocol.js";
 export {
   enableDevtools,

package/src/diagnostics.ts

@@ -1,5 +1,9 @@
 import { getRenderNodeId } from "./debug/index.js";
-import { broadcastDevtoolsMessage } from "./devtools/devtools-server.js";
+import {
+  deleteDiagnostic,
+  insertDiagnostic,
+  isTraceEnabled,
+} from "./debug/trace-writer.js";
 import { getContext } from "./reactivity.js";
 import { getRenderStackSnapshot } from "./render-stack.js";
 import type { SourceLocation } from "./runtime/component.js";
@@ -31,22 +35,31 @@ export interface DiagnosticHandle {
   dismiss(): void;
 }
 
+function buildComponentStack(): DiagnosticStackEntry[] {
+  return getRenderStackSnapshot().map((entry) => ({
+    name: entry.displayName,
+    renderNodeId:
+      entry.context?.meta?.renderNode ?
+        getRenderNodeId(entry.context.meta.renderNode)
+      : undefined,
+    source: entry.source,
+  }));
+}
+
 export class DiagnosticsCollector {
   private entries = new Map<string, Diagnostic>();
   private order: string[] = [];
+  private traceRowIds = new Map<string, number>();
 
   emit(input: DiagnosticInput): DiagnosticHandle {
+    const traceEnabled = isTraceEnabled();
+    // Component stack is only required when a trace consumer will read it,
+    // or when the caller explicitly provided one. Building it walks the full
+    // render stack, which is expensive on hot paths.
     const componentStack =
       input.componentStack ??
-      getRenderStackSnapshot().map((entry) => ({
-        name: entry.displayName,
-        renderNodeId:
-          entry.context?.meta?.renderNode ?
-            getRenderNodeId(entry.context.meta.renderNode)
-          : undefined,
-        source: entry.source,
-      }));
-    const source = input.source ?? componentStack.at(-1)?.source ?? undefined;
+      (traceEnabled ? buildComponentStack() : undefined);
+    const source = input.source ?? componentStack?.at(-1)?.source ?? undefined;
     const id = `diag-${this.order.length + 1}-${Date.now()}`;
     const diagnostic: Diagnostic = {
       id,
@@ -58,14 +71,30 @@ export class DiagnosticsCollector {
     this.entries.set(id, diagnostic);
     this.order.push(id);
 
-    // Broadcast updated diagnostics
-    this.broadcast();
+    if (traceEnabled) {
+      const rowId = insertDiagnostic(
+        diagnostic.message,
+        diagnostic.severity,
+        diagnostic.source?.fileName,
+        diagnostic.source?.lineNumber,
+        diagnostic.source?.columnNumber,
+        diagnostic.componentStack ?
+          JSON.stringify(diagnostic.componentStack)
+        : undefined,
+      );
+      if (rowId !== undefined) {
+        this.traceRowIds.set(id, rowId);
+      }
+    }
 
     return {
       dismiss: () => {
-        this.entries.delete(id);
-        // Broadcast updated diagnostics after dismissal
-        this.broadcast();
+        if (!this.entries.delete(id)) return;
+        const rowId = this.traceRowIds.get(id);
+        if (rowId !== undefined) {
+          this.traceRowIds.delete(id);
+          if (isTraceEnabled()) deleteDiagnostic(rowId);
+        }
       },
     };
   }
@@ -75,13 +104,6 @@ export class DiagnosticsCollector {
       .map((id) => this.entries.get(id))
       .filter((entry): entry is Diagnostic => Boolean(entry));
   }
-
-  private broadcast() {
-    broadcastDevtoolsMessage({
-      type: "diagnostics:report",
-      diagnostics: this.getDiagnostics(),
-    });
-  }
 }
 
 const DIAGNOSTICS_META_KEY = "diagnostics";

package/src/host/node-host.browser.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser stub for Node.js host APIs.
+ *
+ * Replaces `node-host.ts` in browser builds so that no Node.js globals
+ * (`process`, etc.) are referenced.
+ */
+
+export function env(_key: string): string | undefined {
+  return undefined;
+}
+
+export function cwd(): string {
+  return "";
+}
+
+export function stdoutWrite(text: string): void {
+  // eslint-disable-next-line no-console
+  console.log(text);
+}
+
+export function sourceMapsEnabled(): boolean {
+  return false;
+}

package/src/host/node-host.ts

@@ -0,0 +1,22 @@
+/**
+ * Node.js host APIs.
+ *
+ * Provides access to Node.js-specific process APIs. In browser builds this
+ * module is replaced by `node-host.browser.ts` which returns safe defaults.
+ */
+
+export function env(key: string): string | undefined {
+  return process.env[key];
+}
+
+export function cwd(): string {
+  return process.cwd();
+}
+
+export function stdoutWrite(text: string): void {
+  process.stdout.write(text);
+}
+
+export function sourceMapsEnabled(): boolean {
+  return !!(process as any).sourceMapsEnabled;
+}