@alloy-js/core 0.24.0-dev.2 → 0.24.0-dev.7

package/src/debug/trace-writer.ts

@@ -23,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;
@@ -47,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"
@@ -63,7 +66,9 @@ export type ChangeChannel =
   | "diagnostics"
   | "errors"
   | "lifecycle"
-  | "scheduler";
+  | "scheduler"
+  | "components"
+  | "component_roots";
 
 export const ALL_CHANNELS: ChangeChannel[] = [
   "render",
@@ -78,6 +83,8 @@ export const ALL_CHANNELS: ChangeChannel[] = [
   "errors",
   "lifecycle",
   "scheduler",
+  "components",
+  "component_roots",
 ];
 
 export interface ChangeEvent {
@@ -115,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(
@@ -124,7 +133,7 @@ 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
   >[];
@@ -215,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,
@@ -339,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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
@@ -385,9 +436,9 @@ function prepareStatements(): void {
   );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Insert methods
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
+
+// #region Insert methods
 
 export function insertEffect(
   id: number,
@@ -536,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,
@@ -550,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,
@@ -595,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,
@@ -921,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;
@@ -939,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);
@@ -960,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

package/src/devtools-entry.browser.ts

@@ -1,6 +1,11 @@
 export type {
   // Individual server→client message types
   ClientToServerMessage,
+  ComponentAddedMessage,
+  ComponentRemovedMessage,
+  ComponentRootAddedMessage,
+  ComponentRootRemovedMessage,
+  ComponentUpdatedMessage,
   DebuggerInfoMessage,
   DiagnosticRow,
   DiagnosticsReportMessage,

package/src/devtools-entry.ts

@@ -1,6 +1,11 @@
 export type {
   // Individual server→client message types
   ClientToServerMessage,
+  ComponentAddedMessage,
+  ComponentRemovedMessage,
+  ComponentRootAddedMessage,
+  ComponentRootRemovedMessage,
+  ComponentUpdatedMessage,
   DebuggerInfoMessage,
   DiagnosticRow,
   DiagnosticsReportMessage,

package/src/diagnostics.ts

@@ -3,6 +3,7 @@ import {
   deleteDiagnostic,
   insertDiagnostic,
   isTraceEnabled,
+  notifyDiagnosticsReport,
 } from "./debug/trace-writer.js";
 import { getContext } from "./reactivity.js";
 import { getRenderStackSnapshot } from "./render-stack.js";
@@ -107,6 +108,36 @@ export class DiagnosticsCollector {
 }
 
 const DIAGNOSTICS_META_KEY = "diagnostics";
+const diagnosticsByTree = new WeakMap<object, DiagnosticsCollector>();
+
+export function registerDiagnosticsForTree(
+  tree: object,
+  collector: DiagnosticsCollector,
+): void {
+  diagnosticsByTree.set(tree, collector);
+}
+
+export function getRegisteredDiagnosticsForTree(tree: object): Diagnostic[] {
+  return diagnosticsByTree.get(tree)?.getDiagnostics() ?? [];
+}
+
+export function emitDiagnosticForTree(
+  tree: object,
+  input: DiagnosticInput,
+): DiagnosticHandle {
+  return diagnosticsByTree.get(tree)?.emit(input) ?? emitDiagnostic(input);
+}
+
+export function reportDiagnosticsForTree(tree: object): void {
+  const collector = diagnosticsByTree.get(tree);
+  if (!collector) return;
+
+  const diagnostics = collector.getDiagnostics();
+  if (diagnostics.length === 0) return;
+
+  reportDiagnostics(collector);
+  notifyDiagnosticsReport(diagnostics);
+}
 
 export function attachDiagnosticsCollector(collector: DiagnosticsCollector) {
   const context = getContext();