@alloy-js/core 0.23.0-dev.9 → 0.24.0-dev.1

package/src/devtools/devtools-protocol.ts

@@ -1,7 +1,128 @@
 /**
- * Shared protocol types for communication between the Alloy devtools server
- * and the devtools UI client. Both sides import these types to ensure
- * compile-time safety and prevent protocol drift.
+ * Alloy Devtools Protocol
+ * =======================
+ *
+ * Communication protocol between the Alloy debug runtime (core) and the
+ * devtools UI client, transported over WebSocket.
+ *
+ * Message shapes are flat snake_case objects that mirror the SQLite trace-writer
+ * row shapes so no format translation is needed on the wire.
+ *
+ * ─── IDs ─────────────────────────────────────────────────────────────────────
+ *
+ * All entity IDs (effects, refs, reactive-property refs, non-ref targets)
+ * are positive monotonically increasing integers drawn from their respective
+ * counters. Ref IDs and reactive-property IDs share a single counter so
+ * they never collide. There are no negative or sentinel IDs.
+ *
+ * ─── Effects ─────────────────────────────────────────────────────────────────
+ *
+ * An effect is any reactive computation tracked by Alloy's reactivity system.
+ *
+ *   name        Human-readable label. Format varies:
+ *                 "render:ComponentName"         — render effect for a component
+ *                 "memo:For"                     — memo inside a For component
+ *                 "memo:props.children"          — memo from JSX expression
+ *                 "binder:notifySymbolCreated"   — binder infrastructure
+ *                 "myCallback"                   — user effect from fn.name
+ *               For memos created by JSX expression tracking, the babel plugin
+ *               generates a description of the expression (e.g. "props.foo").
+ *
+ *   effect_type Optional effect category string. Set by framework code via
+ *               the debug options on effect(). Values include "render",
+ *               "content", "context", "resource", "binder", "list", "symbol",
+ *               "collection", etc. null when no category was assigned (common
+ *               for memos and user-created effects). Useful for display and
+ *               grouping but NOT used for user-vs-external filtering.
+ *
+ *   source_file / source_line / source_col
+ *               Where the effect was created. Captured via V8 CallSite API
+ *               with source map resolution (when --enable-source-maps is
+ *               active). Points at the component or user code that called
+ *               effect()/memo(), not the reactivity internals. May be null
+ *               if the entire call stack is framework-internal.
+ *
+ *   "User only" filtering:
+ *     Based purely on source_file. An effect is "user code" when its
+ *     source_file resolves to a path OUTSIDE node_modules (i.e. inside the
+ *     user's project). Effects whose source_file is inside node_modules
+ *     (including @alloy-js/* and any third-party library packages) or is
+ *     null are "external" effects. The effect type and name are never used
+ *     for this classification.
+ *
+ * ─── Refs ────────────────────────────────────────────────────────────────────
+ *
+ * A ref is any individually tracked reactive value. There are several kinds:
+ *
+ *   kind="ref"                  Created by alloy's ref() wrapper.
+ *   kind="shallowRef"          Created by alloy's shallowRef() wrapper.
+ *   kind="computed"             Created by alloy's computed() wrapper.
+ *   kind="reactive-property"   A property of a reactive object, lazily
+ *                               registered on first track/trigger. Each
+ *                               (target, key) pair gets its own ref entry.
+ *
+ * Alloy wraps shallowReactive() to capture creation locations. Objects
+ * created via alloy's shallowReactive() wrapper have their creation site
+ * stored in a WeakMap. When a reactive-property ref is registered for such
+ * an object, the property ref inherits the shallowReactive() creation
+ * location. For objects using manual reactivity (e.g. OutputSymbol, which
+ * calls Vue's track()/trigger() directly on `this` rather than going through
+ * alloy's shallowReactive wrapper), the creation site is unknown and the
+ * first track/trigger site is used instead (flagged with is_approx_location).
+ *
+ *   label       Optional human-readable name. Takes priority over kind for
+ *               display. Examples:
+ *                 "memo:For"                        — memo's internal ref
+ *                 "TSOutputSymbol \"Foo\".name"     — reactive property
+ *               When displaying, prefer: label ?? kind. The numeric ID is
+ *               always shown separately as a dimmed suffix, never as part
+ *               of the label text.
+ *
+ *   is_infrastructure
+ *               Boolean. True for refs created by framework internals that
+ *               are implementation details (context.isEmpty, mapJoin index/
+ *               joiner counters, devtools rerender tokens). These are not
+ *               meaningful to end users and are always excluded in
+ *               "user only" mode.
+ *
+ *   is_approx_location
+ *               Boolean. True when the source location was inferred from
+ *               first usage rather than the actual creation site. Applies
+ *               to reactive-property refs whose parent object was not
+ *               created via alloy's shallowReactive() wrapper (e.g.
+ *               OutputSymbol class instances with manual track/trigger).
+ *               The UI should show a subtle indicator (e.g. a small muted
+ *               icon with a tooltip), not a prominent warning.
+ *
+ *   source_file / source_line / source_col
+ *               Where the ref was created. For reactive-property refs from
+ *               shallowReactive() objects, this is the shallowReactive()
+ *               call site. For reactive-property refs from manual-reactivity
+ *               objects, this is the first track site (is_approx_location=1).
+ *               For regular refs/shallowRefs/computed, this is the call site
+ *               with framework-internal stack frames skipped.
+ *
+ *   "User only" filtering:
+ *     A ref is "user code" when is_infrastructure is false AND source_file
+ *     resolves to a path outside node_modules. Infrastructure refs are
+ *     always excluded in user-only mode regardless of source location.
+ *
+ * ─── Edges ───────────────────────────────────────────────────────────────────
+ *
+ * Edges connect effects to refs via track/trigger relationships.
+ * ref_id points to a registered ref. target_id/target_key provide the
+ * raw reactive target info. For ref-backed edges, ref_id == target_id.
+ *
+ * ─── Source Location Resolution ──────────────────────────────────────────────
+ *
+ * Captured at entity creation time via V8's structured CallSite API.
+ * Framework-internal frames (reactivity engine, renderer, scheduler, debug
+ * infra) are skipped so the location points at the component or user code.
+ *
+ * When --enable-source-maps is active, paths and line numbers are resolved
+ * through source maps (.js → .ts). The server reports sourceMapEnabled in
+ * its handshake. Note: pnpm symlinks require realpathSync before
+ * findSourceMap lookup (Node's cache is keyed by real paths).
  */
 
 import type { SourceLocation } from "../debug/effects.js";
@@ -9,91 +130,33 @@ import type { SourceLocation } from "../debug/effects.js";
 export type { SourceLocation };
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Shared types
+// Shared flat row types
 // ─────────────────────────────────────────────────────────────────────────────
 
+export interface DiagnosticRow {
+  message: string;
+  severity?: string;
+  source_file?: string;
+  source_line?: number;
+  source_col?: number;
+  component_stack?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Legacy shared types (used by server code during migration)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** @deprecated Use flat fields on RenderNodeAddedMessage instead. */
 export interface RenderTreeNode {
   id: number;
-  kind:
-    | "root"
-    | "component"
-    | "intrinsic"
-    | "printHook"
-    | "text"
-    | "memo"
-    | "customContext"
-    | "fragment";
+  kind: string;
   name?: string;
   propsSerialized?: string;
   value?: string;
   source?: SourceLocation;
 }
 
-export interface EffectInfo {
-  id: number;
-  name?: string;
-  type?: string;
-  createdAt?: SourceLocation;
-  lastTriggeredByRefId?: number;
-  lastTriggeredAt?: SourceLocation;
-}
-
-export interface RefInfo {
-  id: number;
-  kind?: string;
-  createdAt?: SourceLocation;
-  createdByEffectId?: number;
-}
-
-export interface EffectEdgeInfo {
-  id: number;
-  type: "track" | "trigger" | "triggered-by";
-  effectId: number;
-  refId?: number;
-  targetId?: number;
-  targetKind?: "ref" | "target";
-  targetLabel?: string;
-  targetKey?: string | number;
-  location?: SourceLocation;
-  count?: number;
-}
-
-export interface ScopeInfo {
-  id: number;
-  name: string;
-  parentId: number | null;
-  ownerSymbolId: number | null;
-  renderNodeId?: number | null;
-  isMemberScope: boolean;
-  isTransient?: boolean;
-  metadata?: Record<string, unknown>;
-  debugInfo?: Record<string, unknown>;
-  children?: Array<{ id: number; name?: string }>;
-  spaces?: Array<{
-    key: string;
-    symbols: Array<{ id: number; name?: string }>;
-  }>;
-}
-
-export interface SymbolInfo {
-  id: number;
-  name: string;
-  originalName: string;
-  scopeId: number | null;
-  ownerSymbolId: number | null;
-  renderNodeId?: number | null;
-  isMemberSymbol: boolean;
-  isTransient: boolean;
-  isAlias: boolean;
-  movedToId: number | null;
-  metadata?: Record<string, unknown>;
-  debugInfo?: Record<string, unknown>;
-  memberSpaces?: Array<{
-    key: string;
-    symbols: Array<{ id: number; name?: string }>;
-  }>;
-}
-
+/** @deprecated Use flat fields on RenderErrorMessage instead. */
 export interface RenderErrorStackEntry {
   name: string;
   propsSerialized?: string;
@@ -101,167 +164,277 @@ export interface RenderErrorStackEntry {
   source?: SourceLocation;
 }
 
-export interface DiagnosticInfo {
-  id: string;
-  message: string;
-  severity: string;
-  source?: SourceLocation;
-  componentStack?: Array<{
-    name: string;
-    renderNodeId?: number;
-    source?: SourceLocation;
-  }>;
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Server → Client messages
 // ─────────────────────────────────────────────────────────────────────────────
 
+// -- debugger --
+
 export interface DebuggerInfoMessage {
   type: "debugger:info";
   version: string;
   cwd?: string;
+  sourceMapEnabled: boolean;
 }
 
+// -- render --
+
 export interface RenderResetMessage {
   type: "render:reset";
 }
 
 export interface RenderNodeAddedMessage {
-  type: "render:nodeAdded";
-  parentId: number | null;
-  node: RenderTreeNode;
+  type: "render:node_added";
+  id: number;
+  parent_id: number | null;
+  kind: string;
+  name?: string;
+  props?: string;
+  value?: string;
+  source_file?: string;
+  source_line?: number;
+  source_col?: number;
+  context_id?: number | null;
+  seq: number;
 }
 
 export interface RenderNodeUpdatedMessage {
-  type: "render:nodeUpdated";
+  type: "render:node_updated";
   id: number;
-  propsSerialized?: string;
+  props?: string;
 }
 
 export interface RenderNodeRemovedMessage {
-  type: "render:nodeRemoved";
-  parentId: number | null;
+  type: "render:node_removed";
   id: number;
-  name?: string;
 }
 
 export interface RenderErrorMessage {
   type: "render:error";
-  id: number;
   name?: string;
   message?: string;
   stack?: string;
-  componentStack: RenderErrorStackEntry[];
+  component_stack?: string;
+  seq: number;
 }
 
 export interface RenderCompleteMessage {
   type: "render:complete";
 }
 
+// -- flush --
+
 export interface FlushJobsCompleteMessage {
-  type: "flushJobs:complete";
+  type: "flush:complete";
 }
 
-export interface DirectoryAddedMessage {
-  type: "files:directoryAdded";
-  path: string;
+// -- effects --
+
+export interface EffectAddedMessage {
+  type: "effect:added";
+  id: number;
+  name?: string;
+  effect_type?: string;
+  context_id?: number | null;
+  owner_context_id?: number | null;
+  component?: string;
+  source_file?: string;
+  source_line?: number;
+  source_col?: number;
+  source_package?: string;
+  is_infrastructure?: number;
+  seq: number;
 }
 
-export interface DirectoryRemovedMessage {
-  type: "files:directoryRemoved";
-  path: string;
+export interface EffectUpdatedMessage {
+  type: "effect:updated";
+  id: number;
+  name?: string;
+  effect_type?: string;
+  context_id?: number | null;
+  owner_context_id?: number | null;
+  component?: string;
+  source_file?: string;
+  source_line?: number;
+  source_col?: number;
+  source_package?: string;
+  is_infrastructure?: number;
+  seq: number;
 }
 
-export interface FileAddedMessage {
-  type: "files:fileAdded";
-  path: string;
-  filetype: string;
-  renderNodeId?: number;
+// -- refs --
+
+export interface RefAddedMessage {
+  type: "ref:added";
+  id: number;
+  kind?: string;
+  label?: string;
+  created_by_effect_id?: number;
+  source_file?: string;
+  source_line?: number;
+  source_col?: number;
+  source_package?: string;
+  is_approx_location?: number;
+  seq: number;
 }
 
-export interface FileRemovedMessage {
-  type: "files:fileRemoved";
-  path: string;
+// -- edges --
+
+export interface EffectTrackMessage {
+  type: "edge:track";
+  seq: number;
+  effect_id: number;
+  ref_id?: number;
+  target_id?: number;
+  target_kind?: string;
+  target_label?: string;
+  target_key?: string;
 }
 
-export interface FileUpdatedMessage {
-  type: "files:fileUpdated";
-  path: string;
-  filetype: string;
-  contents: string;
+export interface EffectTriggerMessage {
+  type: "edge:trigger";
+  seq: number;
+  effect_id: number;
+  caused_by?: number;
+  ref_id?: number;
+  target_id?: number;
+  target_kind?: string;
+  target_label?: string;
+  target_key?: string;
 }
 
-export interface ScopeCreateMessage {
-  type: "scope:create";
-  scope: ScopeInfo;
+export interface EffectEdgeUpdatedMessage {
+  type: "edge:updated";
+  seq: number;
+  effect_id: number;
+  caused_by?: number;
+  ref_id?: number;
+  target_id?: number;
+  target_kind?: string;
+  target_label?: string;
+  target_key?: string;
 }
 
-export interface ScopeUpdateMessage {
-  type: "scope:update";
-  scope: ScopeInfo;
+// -- effect lifecycle --
+
+export interface EffectLifecycleMessage {
+  type: "effect:lifecycle";
+  seq: number;
+  effect_id: number;
+  event: string;
+  trigger_ref_id?: number;
 }
 
-export interface ScopeDeleteMessage {
-  type: "scope:delete";
+// -- scopes --
+
+export interface ScopeAddedMessage {
+  type: "scope:added";
   id: number;
+  name: string;
+  parent_id?: number | null;
+  owner_symbol_id?: number | null;
+  render_node_id?: number | null;
+  is_member_scope?: number;
+  is_transient?: number;
+  metadata?: string;
+  seq: number;
 }
 
-export interface SymbolCreateMessage {
-  type: "symbol:create";
-  symbol: SymbolInfo;
+export interface ScopeUpdatedMessage {
+  type: "scope:updated";
+  id: number;
+  name: string;
+  parent_id?: number | null;
+  owner_symbol_id?: number | null;
+  render_node_id?: number | null;
+  is_member_scope?: number;
+  is_transient?: number;
+  metadata?: string;
+  seq: number;
 }
 
-export interface SymbolUpdateMessage {
-  type: "symbol:update";
-  symbol: SymbolInfo;
+export interface ScopeRemovedMessage {
+  type: "scope:removed";
+  id: number;
 }
 
-export interface SymbolDeleteMessage {
-  type: "symbol:delete";
+// -- symbols --
+
+export interface SymbolAddedMessage {
+  type: "symbol:added";
+  id: number;
+  name: string;
+  original_name?: string;
+  scope_id?: number | null;
+  owner_symbol_id?: number | null;
+  render_node_id?: number | null;
+  is_member?: number;
+  is_transient?: number;
+  is_alias?: number;
+  moved_to_id?: number | null;
+  metadata?: string;
+  seq: number;
+}
+
+export interface SymbolUpdatedMessage {
+  type: "symbol:updated";
+  id: number;
+  name: string;
+  original_name?: string;
+  scope_id?: number | null;
+  owner_symbol_id?: number | null;
+  render_node_id?: number | null;
+  is_member?: number;
+  is_transient?: number;
+  is_alias?: number;
+  moved_to_id?: number | null;
+  metadata?: string;
+  seq: number;
+}
+
+export interface SymbolRemovedMessage {
+  type: "symbol:removed";
   id: number;
 }
 
-export interface EffectAddedMessage {
-  type: "effect:effectAdded";
-  effect: EffectInfo;
-}
+// -- files --
 
-export interface EffectUpdatedMessage {
-  type: "effect:effectUpdated";
-  effect: EffectInfo;
+export interface FileAddedMessage {
+  type: "file:added";
+  path: string;
+  filetype?: string;
+  render_node_id?: number;
+  seq: number;
 }
 
-export interface RefAddedMessage {
-  type: "effect:refAdded";
-  ref: RefInfo;
+export interface FileUpdatedMessage {
+  type: "file:updated";
+  path: string;
+  content?: string;
 }
 
-export interface EffectTrackMessage {
-  type: "effect:track";
-  edge: EffectEdgeInfo;
-  message?: string;
+export interface FileRemovedMessage {
+  type: "file:removed";
+  path: string;
 }
 
-export interface EffectTriggerMessage {
-  type: "effect:trigger";
-  edge: EffectEdgeInfo;
-  message?: string;
+// -- directories --
+
+export interface DirectoryAddedMessage {
+  type: "directory:added";
+  path: string;
 }
 
-export interface EffectEdgeUpdatedMessage {
-  type: "effect:edgeUpdated";
-  edge: EffectEdgeInfo;
+export interface DirectoryRemovedMessage {
+  type: "directory:removed";
+  path: string;
 }
 
+// -- diagnostics --
+
 export interface DiagnosticsReportMessage {
   type: "diagnostics:report";
-  diagnostics: DiagnosticInfo[];
-}
-
-export interface BatchMessage {
-  type: "batch";
-  messages: ServerToClientMessage[];
+  diagnostics: DiagnosticRow[];
 }
 
 export type ServerToClientMessage =
@@ -273,30 +446,40 @@ export type ServerToClientMessage =
   | RenderErrorMessage
   | RenderCompleteMessage
   | FlushJobsCompleteMessage
-  | DirectoryAddedMessage
-  | DirectoryRemovedMessage
-  | FileAddedMessage
-  | FileRemovedMessage
-  | FileUpdatedMessage
-  | ScopeCreateMessage
-  | ScopeUpdateMessage
-  | ScopeDeleteMessage
-  | SymbolCreateMessage
-  | SymbolUpdateMessage
-  | SymbolDeleteMessage
   | EffectAddedMessage
   | EffectUpdatedMessage
   | RefAddedMessage
   | EffectTrackMessage
   | EffectTriggerMessage
   | EffectEdgeUpdatedMessage
-  | DiagnosticsReportMessage
-  | BatchMessage;
+  | EffectLifecycleMessage
+  | ScopeAddedMessage
+  | ScopeUpdatedMessage
+  | ScopeRemovedMessage
+  | SymbolAddedMessage
+  | SymbolUpdatedMessage
+  | SymbolRemovedMessage
+  | FileAddedMessage
+  | FileUpdatedMessage
+  | FileRemovedMessage
+  | DirectoryAddedMessage
+  | DirectoryRemovedMessage
+  | DiagnosticsReportMessage;
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Client → Server messages
 // ─────────────────────────────────────────────────────────────────────────────
 
+export interface SubscribeMessage {
+  type: "subscribe";
+  channels: string[];
+}
+
+export interface UnsubscribeMessage {
+  type: "unsubscribe";
+  channels: string[];
+}
+
 export interface RerenderRequestMessage {
   type: "render:rerender";
   id: number;
@@ -308,5 +491,7 @@ export interface RerenderBreakRequestMessage {
 }
 
 export type ClientToServerMessage =
+  | SubscribeMessage
+  | UnsubscribeMessage
   | RerenderRequestMessage
   | RerenderBreakRequestMessage;

package/src/devtools/devtools-server.browser.ts

@@ -1,10 +1,5 @@
 // Browser stub for devtools-server - devtools are not supported in browsers
 
-export interface DevtoolsMessage {
-  type: string;
-  [key: string]: unknown;
-}
-
 export interface DevtoolsIncomingMessage {
   type: string;
   [key: string]: unknown;
@@ -38,10 +33,6 @@ export async function initDevtoolsIfEnabled(): Promise<void> {
   // No-op in browser
 }
 
-export function broadcastDevtoolsMessage(_message: DevtoolsMessage): void {
-  // No-op in browser
-}
-
 export function registerDevtoolsMessageHandler(
   _handler: (message: DevtoolsIncomingMessage) => void,
 ): () => void {
@@ -69,3 +60,7 @@ export async function enableDevtoolsAndConnect(
 export async function resetDevtoolsServerForTests(): Promise<void> {
   // No-op in browser
 }
+
+export function refreshDebugState(): void {
+  // No-op in browser
+}