@alloy-js/core 0.24.0-dev.1 → 0.24.0-dev.6

package/src/debug/trace-db.browser.ts

@@ -0,0 +1,12 @@
+/**
+ * Browser stub for trace database initialization.
+ *
+ * Replaces `trace-db.ts` in browser builds. Returns null so that
+ * all trace-writer functions (which guard on `if (!db) return`) become no-ops.
+ */
+
+export type DatabaseSync = null;
+
+export async function openTraceDatabase(_path: string): Promise<null> {
+  return null;
+}

package/src/debug/trace-db.ts

@@ -0,0 +1,42 @@
+/**
+ * Database initialization for the trace writer.
+ *
+ * Isolates the `node:sqlite` and `node:fs` dependencies so that
+ * `trace-writer.ts` itself remains browser-safe (all functions no-op
+ * when db is null). In browser builds this module is replaced by
+ * `trace-db.browser.ts` which always returns null.
+ */
+import type { DatabaseSync as DatabaseSyncType } from "node:sqlite";
+
+export type { DatabaseSyncType as DatabaseSync };
+
+/**
+ * Opens a fresh SQLite database at the given path, removing any existing file.
+ * Returns the opened database instance.
+ */
+export async function openTraceDatabase(
+  path: string,
+): Promise<DatabaseSyncType> {
+  const { DatabaseSync } = await import("node:sqlite");
+  const fs = await import("node:fs");
+  // Remove existing trace file so each run starts fresh
+  try {
+    fs.unlinkSync(path);
+  } catch {
+    /* ignore missing */
+  }
+  try {
+    fs.unlinkSync(path + "-wal");
+  } catch {
+    /* ignore missing */
+  }
+  try {
+    fs.unlinkSync(path + "-shm");
+  } catch {
+    /* ignore missing */
+  }
+  const db = new DatabaseSync(path);
+  db.exec("PRAGMA journal_mode=WAL");
+  db.exec("PRAGMA synchronous=NORMAL");
+  return db;
+}

package/src/debug/trace-writer.ts

@@ -5,12 +5,10 @@
  * built-in `node:sqlite` module. The database can be queried by the
  * `alloy-trace` CLI or the devtools WebSocket server.
  */
-import type {
-  DatabaseSync as DatabaseSyncType,
-  StatementSync,
-} from "node:sqlite";
+import type { StatementSync } from "node:sqlite";
+import { type DatabaseSync, openTraceDatabase } from "./trace-db.js";
 
-let db: DatabaseSyncType | null = null;
+let db: DatabaseSync | null = null;
 let seq = 0;
 
 // Prepared statements (initialized in initTrace)
@@ -25,6 +23,11 @@ let stmtInsertRenderNode: StatementSync;
 let stmtUpdateRenderNode: StatementSync;
 let stmtUpdateRenderNodeContext: StatementSync;
 let stmtDeleteRenderNode: StatementSync;
+let stmtInsertComponentInstance: StatementSync;
+let stmtUpdateComponentInstanceProps: StatementSync;
+let stmtDeleteComponentInstance: StatementSync;
+let stmtInsertComponentRoot: StatementSync;
+let stmtDeleteComponentRoot: StatementSync;
 let stmtInsertSymbol: StatementSync;
 let stmtUpdateSymbol: StatementSync;
 let stmtDeleteSymbol: StatementSync;
@@ -49,9 +52,7 @@ export function nextSeq(): number {
   return seq++;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Change notification bus — streams SQLite changes to devtools WS server
-// ─────────────────────────────────────────────────────────────────────────────
+// #region Change notification bus
 
 export type ChangeChannel =
   | "render"
@@ -65,7 +66,9 @@ export type ChangeChannel =
   | "diagnostics"
   | "errors"
   | "lifecycle"
-  | "scheduler";
+  | "scheduler"
+  | "components"
+  | "component_roots";
 
 export const ALL_CHANNELS: ChangeChannel[] = [
   "render",
@@ -80,6 +83,8 @@ export const ALL_CHANNELS: ChangeChannel[] = [
   "errors",
   "lifecycle",
   "scheduler",
+  "components",
+  "component_roots",
 ];
 
 export interface ChangeEvent {
@@ -117,6 +122,8 @@ const channelTableMap: Record<string, string> = {
   diagnostics: "diagnostics",
   errors: "render_errors",
   scheduler: "scheduler_jobs",
+  components: "component_instances",
+  component_roots: "component_roots",
 };
 
 export function queryChannel(
@@ -126,35 +133,15 @@ export function queryChannel(
   const table = channelTableMap[channel];
   if (!table) return [];
   if (!/^[a-z_]+$/.test(table)) return [];
-  return db.prepare(`SELECT * FROM ${table}`).all() as Record<
+  return db.prepare(`SELECT * FROM ${table} ORDER BY seq`).all() as Record<
     string,
     unknown
   >[];
 }
 
 export async function initTrace(path: string): Promise<void> {
-  // Dynamic import to avoid failing in environments without node:sqlite
-  const { DatabaseSync } = await import("node:sqlite");
-  const fs = await import("node:fs");
-  // Remove existing trace file so each run starts fresh
-  try {
-    fs.unlinkSync(path);
-  } catch {
-    /* ignore missing */
-  }
-  try {
-    fs.unlinkSync(path + "-wal");
-  } catch {
-    /* ignore missing */
-  }
-  try {
-    fs.unlinkSync(path + "-shm");
-  } catch {
-    /* ignore missing */
-  }
-  db = new DatabaseSync(path);
-  db.exec("PRAGMA journal_mode=WAL");
-  db.exec("PRAGMA synchronous=NORMAL");
+  db = await openTraceDatabase(path);
+  if (!db) return;
   createSchema();
   prepareStatements();
 }
@@ -237,6 +224,31 @@ function createSchema(): void {
     CREATE INDEX IF NOT EXISTS idx_render_nodes_parent ON render_nodes(parent_id);
     CREATE INDEX IF NOT EXISTS idx_render_nodes_context ON render_nodes(context_id);
 
+    CREATE TABLE IF NOT EXISTS component_instances (
+      id                   INTEGER PRIMARY KEY,
+      parent_id            INTEGER,
+      name                 TEXT NOT NULL,
+      props                TEXT,
+      source_file          TEXT,
+      source_line          INTEGER,
+      source_col           INTEGER,
+      context_id           INTEGER,
+      seq                  INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_component_instances_parent ON component_instances(parent_id);
+    CREATE INDEX IF NOT EXISTS idx_component_instances_name ON component_instances(name);
+    CREATE INDEX IF NOT EXISTS idx_component_instances_context ON component_instances(context_id);
+
+    CREATE TABLE IF NOT EXISTS component_roots (
+      component_id         INTEGER NOT NULL,
+      render_node_id       INTEGER NOT NULL,
+      ordinal              INTEGER NOT NULL,
+      seq                  INTEGER,
+      PRIMARY KEY (component_id, render_node_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_component_roots_component ON component_roots(component_id);
+    CREATE INDEX IF NOT EXISTS idx_component_roots_node ON component_roots(render_node_id);
+
     CREATE TABLE IF NOT EXISTS symbols (
       id                   INTEGER PRIMARY KEY,
       name                 TEXT NOT NULL,
@@ -361,6 +373,23 @@ function prepareStatements(): void {
     `UPDATE render_nodes SET context_id = ? WHERE id = ?`,
   );
   stmtDeleteRenderNode = db!.prepare(`DELETE FROM render_nodes WHERE id = ?`);
+  stmtInsertComponentInstance = db!.prepare(
+    `INSERT OR REPLACE INTO component_instances (id, parent_id, name, props, source_file, source_line, source_col, context_id, seq)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  );
+  stmtUpdateComponentInstanceProps = db!.prepare(
+    `UPDATE component_instances SET props = ? WHERE id = ?`,
+  );
+  stmtDeleteComponentInstance = db!.prepare(
+    `DELETE FROM component_instances WHERE id = ?`,
+  );
+  stmtInsertComponentRoot = db!.prepare(
+    `INSERT OR REPLACE INTO component_roots (component_id, render_node_id, ordinal, seq)
+     VALUES (?, ?, ?, ?)`,
+  );
+  stmtDeleteComponentRoot = db!.prepare(
+    `DELETE FROM component_roots WHERE component_id = ? AND render_node_id = ?`,
+  );
   stmtInsertSymbol = db!.prepare(
     `INSERT OR REPLACE INTO symbols (id, name, original_name, scope_id, owner_symbol_id, render_node_id, is_member, is_transient, is_alias, metadata, seq)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
@@ -407,9 +436,9 @@ function prepareStatements(): void {
   );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Insert methods
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Insert methods
 
 export function insertEffect(
   id: number,
@@ -558,6 +587,10 @@ export function insertSchedulerFlush(jobsRun: number): void {
   stmtInsertSchedulerFlush.run(nextSeq(), jobsRun);
 }
 
+// Track live render IDs and parent -> children edges so duplicate removals are
+// ignored and child sets stay consistent with render-layer lifecycle events.
+const renderChildren = new Map<number, Set<number>>();
+const liveRenderIds = new Set<number>();
 export function insertRenderNode(
   id: number,
   parentId: number | null,
@@ -572,6 +605,15 @@ export function insertRenderNode(
 ): void {
   if (!db) return;
   const s = nextSeq();
+  if (parentId !== null) {
+    let set = renderChildren.get(parentId);
+    if (!set) {
+      set = new Set();
+      renderChildren.set(parentId, set);
+    }
+    set.add(id);
+  }
+  liveRenderIds.add(id);
   stmtInsertRenderNode.run(
     id,
     parentId,
@@ -617,10 +659,94 @@ export function updateRenderNodeContext(id: number, contextId: number): void {
 
 export function deleteRenderNode(id: number): void {
   if (!db) return;
+  if (!liveRenderIds.has(id)) return;
+  liveRenderIds.delete(id);
+  // Detach from parent's child set.
+  for (const set of renderChildren.values()) set.delete(id);
+  renderChildren.delete(id);
   stmtDeleteRenderNode.run(id);
   notifyChange("render", "removed", { id });
 }
 
+export function insertComponentInstance(
+  id: number,
+  parentId: number | null,
+  name: string,
+  props: string | undefined,
+  sourceFile: string | undefined,
+  sourceLine: number | undefined,
+  sourceCol: number | undefined,
+  contextId: number | null,
+): void {
+  if (!db) return;
+  const s = nextSeq();
+  stmtInsertComponentInstance.run(
+    id,
+    parentId,
+    name,
+    props ?? null,
+    sourceFile ?? null,
+    sourceLine ?? null,
+    sourceCol ?? null,
+    contextId,
+    s,
+  );
+  notifyChange("components", "added", {
+    id,
+    parent_id: parentId,
+    name,
+    props: props ?? null,
+    source_file: sourceFile ?? null,
+    source_line: sourceLine ?? null,
+    source_col: sourceCol ?? null,
+    context_id: contextId,
+    seq: s,
+  });
+}
+
+export function updateComponentInstanceProps(
+  id: number,
+  props: string | undefined,
+): void {
+  if (!db) return;
+  stmtUpdateComponentInstanceProps.run(props ?? null, id);
+  notifyChange("components", "updated", { id, props: props ?? null });
+}
+
+export function deleteComponentInstance(id: number): void {
+  if (!db) return;
+  stmtDeleteComponentInstance.run(id);
+  notifyChange("components", "removed", { id });
+}
+
+export function insertComponentRoot(
+  componentId: number,
+  renderNodeId: number,
+  ordinal: number,
+): void {
+  if (!db) return;
+  const s = nextSeq();
+  stmtInsertComponentRoot.run(componentId, renderNodeId, ordinal, s);
+  notifyChange("component_roots", "added", {
+    component_id: componentId,
+    render_node_id: renderNodeId,
+    ordinal,
+    seq: s,
+  });
+}
+
+export function deleteComponentRoot(
+  componentId: number,
+  renderNodeId: number,
+): void {
+  if (!db) return;
+  stmtDeleteComponentRoot.run(componentId, renderNodeId);
+  notifyChange("component_roots", "removed", {
+    component_id: componentId,
+    render_node_id: renderNodeId,
+  });
+}
+
 export function insertSymbol(
   id: number,
   name: string,
@@ -943,9 +1069,9 @@ export function insertSourceMap(
   stmtInsertSourceMap.run(outputPath, mapJson, outputText ?? null);
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Transaction helpers
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Transaction helpers
 
 export function beginTransaction(): void {
   if (!db) return;
@@ -961,15 +1087,19 @@ export function closeTrace(): void {
   db?.close();
   db = null;
   stmtDeleteDiagnostic = undefined;
+  renderChildren.clear();
+  liveRenderIds.clear();
 }
 
 export function resetTrace(): void {
   seq = 0;
+  renderChildren.clear();
+  liveRenderIds.clear();
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Lifecycle signals — broadcast to all WS clients regardless of subscription
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Lifecycle signals
 
 export function notifyRenderReset(): void {
   notifyChange("render", "reset", { _signal: "render:reset" } as any);
@@ -982,3 +1112,5 @@ export function notifyRenderComplete(): void {
 export function notifyFlushComplete(): void {
   notifyChange("lifecycle", "added", { _signal: "flushJobs:complete" } as any);
 }
+
+// #endregion

package/src/debug/trace.ts

@@ -197,26 +197,6 @@ export const TracePhase = {
       subarea: "appendChild",
       bg: { r: 100, g: 50, b: 0 },
     },
-    appendTextNode: {
-      area: "render",
-      subarea: "appendChild.textNode",
-      bg: { r: 100, g: 50, b: 0 },
-    },
-    appendCachedFragment: {
-      area: "render",
-      subarea: "appendChild.cachedFragment",
-      bg: { r: 100, g: 50, b: 0 },
-    },
-    appendCustomContext: {
-      area: "render",
-      subarea: "appendChild.customContext",
-      bg: { r: 100, g: 50, b: 0 },
-    },
-    appendPrintHook: {
-      area: "render",
-      subarea: "appendChild.printHook",
-      bg: { r: 100, g: 50, b: 0 },
-    },
     appendComponent: {
       area: "render",
       subarea: "appendChild.component",

package/src/devtools/devtools-protocol.ts

@@ -209,6 +209,44 @@ export interface RenderNodeRemovedMessage {
   id: number;
 }
 
+export interface ComponentAddedMessage {
+  type: "component:added";
+  id: number;
+  parent_id: number | null;
+  name: string;
+  props?: string;
+  source_file?: string;
+  source_line?: number;
+  source_col?: number;
+  context_id?: number | null;
+  seq: number;
+}
+
+export interface ComponentUpdatedMessage {
+  type: "component:updated";
+  id: number;
+  props?: string;
+}
+
+export interface ComponentRemovedMessage {
+  type: "component:removed";
+  id: number;
+}
+
+export interface ComponentRootAddedMessage {
+  type: "component:root_added";
+  component_id: number;
+  render_node_id: number;
+  ordinal: number;
+  seq: number;
+}
+
+export interface ComponentRootRemovedMessage {
+  type: "component:root_removed";
+  component_id: number;
+  render_node_id: number;
+}
+
 export interface RenderErrorMessage {
   type: "render:error";
   name?: string;
@@ -443,6 +481,11 @@ export type ServerToClientMessage =
   | RenderNodeAddedMessage
   | RenderNodeUpdatedMessage
   | RenderNodeRemovedMessage
+  | ComponentAddedMessage
+  | ComponentUpdatedMessage
+  | ComponentRemovedMessage
+  | ComponentRootAddedMessage
+  | ComponentRootRemovedMessage
   | RenderErrorMessage
   | RenderCompleteMessage
   | FlushJobsCompleteMessage

package/src/devtools/devtools-server.ts

@@ -20,9 +20,7 @@ import {
   type DevtoolsTransportState,
 } from "./devtools-transport.js";
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Public types
-// ─────────────────────────────────────────────────────────────────────────────
+// #region Public types
 
 export interface DevtoolsIncomingMessage {
   type: string;
@@ -39,9 +37,9 @@ export interface EnableDevtoolsOptions {
   port?: number;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Session state
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Session state
 
 let transportState: DevtoolsTransportState | null = null;
 let transportPromise: Promise<DevtoolsTransportState> | null = null;
@@ -55,9 +53,9 @@ let tempDbPath: string | null = null;
 let subscribedPromise: Promise<void> | null = null;
 let resolveSubscribed: (() => void) | null = null;
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Per-client subscription state
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Per-client subscription state
 
 interface ClientState {
   subscriptions: Set<ChangeChannel>;
@@ -73,6 +71,15 @@ function eventToMessageType(event: ChangeEvent): string {
       removed: "render:node_removed",
       reset: "render:reset",
     },
+    components: {
+      added: "component:added",
+      updated: "component:updated",
+      removed: "component:removed",
+    },
+    component_roots: {
+      added: "component:root_added",
+      removed: "component:root_removed",
+    },
     effects: { added: "effect:added", updated: "effect:updated" },
     refs: { added: "ref:added" },
     edges: { added: `edge:${(event.data as any).edge_type ?? "track"}` },
@@ -108,6 +115,8 @@ function channelToInitialMessageType(
 ): string {
   const map: Record<string, string> = {
     render: "render:node_added",
+    components: "component:added",
+    component_roots: "component:root_added",
     effects: "effect:added",
     refs: "ref:added",
     symbols: "symbol:added",
@@ -141,9 +150,9 @@ function sendInitialState(socket: any, channels: ChangeChannel[]): void {
   }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Environment helpers
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Environment helpers
 
 function isNodeEnvironment() {
   return (
@@ -158,12 +167,24 @@ function isNodeEnvironment() {
 let _envDebugEnabled: boolean =
   isNodeEnvironment() && Boolean(process.env.ALLOY_DEBUG);
 
+// Cached value of `devtoolsExplicitlyEnabled || _envDebugEnabled`. This
+// function is called on hot paths (every effect/scheduler tick), so we
+// avoid recomputing the OR + the `isNodeEnvironment` check on every call.
+// The cache is invalidated whenever either underlying flag mutates.
+let _devtoolsEnabledCache: boolean = isNodeEnvironment() && _envDebugEnabled;
+
+function refreshDevtoolsEnabledCache(): void {
+  _devtoolsEnabledCache =
+    isNodeEnvironment() && (devtoolsExplicitlyEnabled || _envDebugEnabled);
+}
+
 /**
  * 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);
+  refreshDevtoolsEnabledCache();
 }
 
 function getCwd() {
@@ -183,14 +204,13 @@ function resolveDebugPort() {
   return parsed;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Query functions
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Query functions
 
 /** Returns true when devtools are enabled (via env var or explicit call). */
 export function isDevtoolsEnabled() {
-  if (!isNodeEnvironment()) return false;
-  return devtoolsExplicitlyEnabled || _envDebugEnabled;
+  return _devtoolsEnabledCache;
 }
 
 /** Returns true when a devtools client is currently connected. */
@@ -204,9 +224,9 @@ export function getDevtoolsServerInfo(): DevtoolsServerInfo | null {
   return { port: transportState.port, connected: transportState.connected };
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Temp SQLite for devtools
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Temp SQLite for devtools
 
 async function ensureSqliteForDevtools(): Promise<void> {
   if (isTraceEnabled()) return;
@@ -236,9 +256,9 @@ async function ensureSqliteForDevtools(): Promise<void> {
   });
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Server lifecycle
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Server lifecycle
 
 async function ensureServer(): Promise<DevtoolsTransportState> {
   if (transportState) return transportState;
@@ -350,9 +370,9 @@ async function ensureServer(): Promise<DevtoolsTransportState> {
   return transportPromise;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Public API
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Public API
 
 /**
  * Wait for a devtools client to connect before proceeding.
@@ -371,6 +391,7 @@ async function ensureServer(): Promise<DevtoolsTransportState> {
  */
 export async function waitForDevtoolsConnection(): Promise<void> {
   devtoolsExplicitlyEnabled = true;
+  refreshDevtoolsEnabledCache();
   const server = await ensureServer();
   if (!server.connected) {
     await server.ready;
@@ -392,6 +413,7 @@ export async function enableDevtools(
   options?: EnableDevtoolsOptions,
 ): Promise<DevtoolsServerInfo> {
   devtoolsExplicitlyEnabled = true;
+  refreshDevtoolsEnabledCache();
   devtoolsInitialized = true;
   if (options?.port !== undefined) {
     configuredPort = options.port;
@@ -435,9 +457,9 @@ export async function enableDevtoolsAndConnect(
   return { port: transportState!.port, connected: true };
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Messaging
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Messaging
 
 /** Register a handler for incoming devtools messages. Returns an unsubscribe function. */
 export function registerDevtoolsMessageHandler(
@@ -457,9 +479,9 @@ export function assertDevtoolsConnectedForSyncRender() {
   }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Test utilities
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Test utilities
 
 /** Reset all devtools state. For use in tests only. */
 export async function resetDevtoolsServerForTests() {
@@ -471,6 +493,7 @@ export async function resetDevtoolsServerForTests() {
   transportState = null;
   transportPromise = null;
   devtoolsExplicitlyEnabled = false;
+  refreshDevtoolsEnabledCache();
   devtoolsInitialized = false;
   configuredPort = undefined;
   loggedDevtoolsLinks = false;
@@ -481,3 +504,5 @@ export async function resetDevtoolsServerForTests() {
   // Close the trace DB so each test starts fresh
   closeTrace();
 }
+
+// #endregion