@alloy-js/core 0.23.0-dev.10 → 0.23.0-dev.11

package/src/reactivity.ts

@@ -14,14 +14,10 @@ import {
   toRef as vueToRef,
   toRefs as vueToRefs,
 } from "@vue/reactivity";
-import {
-  captureSourceLocation,
-  debug,
-  isDevtoolsEnabled,
-} from "./debug/index.js";
+import { captureSourceLocation, debug, isDebugEnabled } from "./debug/index.js";
 import { RenderedTextTree } from "./render.js";
 import { Children, ComponentCreator } from "./runtime/component.js";
-import { scheduler } from "./scheduler.js";
+import { scheduler, setLastTriggerRef } from "./scheduler.js";
 import type { OutputSymbol } from "./symbols/output-symbol.js";
 
 if ((globalThis as any).__ALLOY__) {
@@ -135,7 +131,9 @@ function resolveOwnerEffectContextId(context: Context): number | null {
  * ContentSlot, mapJoin). Most contexts don't need an isEmpty ref.
  */
 export function ensureIsEmpty(context: Context): Ref<boolean> {
-  context.isEmpty ??= ref(context.childrenWithContent === 0);
+  context.isEmpty ??= ref(context.childrenWithContent === 0, {
+    isInfrastructure: true,
+  });
   return context.isEmpty;
 }
 
@@ -203,7 +201,10 @@ export function findCurrentEffectId(): number | undefined {
 }
 
 export function memo<T>(fn: () => T, equal?: boolean, name?: string): () => T {
-  const o = shallowRef<T>();
+  const memoLabel = name ? `memo:${name}` : "memo";
+  const o = shallowRef<T>(undefined as T, {
+    label: memoLabel,
+  });
   effect(
     (prev) => {
       const res = fn();
@@ -283,6 +284,23 @@ export function effect<T>(
           refId: id,
           targetKey,
         });
+      } else if (
+        typeof event.target === "object" &&
+        event.target !== null &&
+        targetKey !== undefined
+      ) {
+        const id = reactivePropertyRefId(event.target, targetKey);
+        debug.effect.ensureReactivePropertyRef({
+          id,
+          target: event.target,
+          key: targetKey,
+        });
+        debug.effect.track({
+          effectId,
+          target: event.target,
+          refId: id,
+          targetKey,
+        });
       } else {
         debug.effect.track({
           effectId,
@@ -292,8 +310,21 @@ export function effect<T>(
       }
     };
     effectOpts.onTrigger = (event: any) => {
+      if (!("target" in event)) {
+        // Vue Dep.notify() chain propagation — no actual reactive target.
+        // Skip recording: these are computed→subscriber notifications without
+        // a meaningful target reference.
+        return;
+      }
       const targetKey =
         typeof event.key === "symbol" ? event.key.toString() : event.key;
+      // findCurrentEffectId() works because onTrigger fires synchronously
+      // during the mutation, so globalContext still points to the producer.
+      const producerEffectId = findCurrentEffectId();
+      const causedBy =
+        producerEffectId !== undefined && producerEffectId !== effectId ?
+          producerEffectId
+        : undefined;
       if (isRef(event.target)) {
         const id = refId(event.target);
         debug.effect.ensureRef({ id, kind: "ref" });
@@ -302,14 +333,34 @@ export function effect<T>(
           target: event.target,
           refId: id,
           targetKey,
-          kind: "triggered-by",
+          causedBy,
         });
+        setLastTriggerRef(effectId, id);
+      } else if (
+        typeof event.target === "object" &&
+        event.target !== null &&
+        targetKey !== undefined
+      ) {
+        const id = reactivePropertyRefId(event.target, targetKey);
+        debug.effect.ensureReactivePropertyRef({
+          id,
+          target: event.target,
+          key: targetKey,
+        });
+        debug.effect.trigger({
+          effectId,
+          target: event.target,
+          refId: id,
+          targetKey,
+          causedBy,
+        });
+        setLastTriggerRef(effectId, id);
       } else {
         debug.effect.trigger({
           effectId,
           target: event.target,
           targetKey,
-          kind: "triggered-by",
+          causedBy,
         });
       }
     };
@@ -393,7 +444,7 @@ export function ref<T>(
 ): Ref<T> {
   const result = vueRef(value) as Ref<T>;
   debug.effect.registerRef({
-    id: refId(result, options?.isInfrastructure),
+    id: refId(result),
     kind: "ref",
     createdAt: captureSourceLocation(),
     createdByEffectId: globalContext?.meta?.effectId,
@@ -417,18 +468,19 @@ export function shallowReactive<T extends object>(
   target: T,
 ): ShallowReactive<T> {
   const result = vueShallowReactive(target);
-  if (isDevtoolsEnabled()) {
+  if (isDebugEnabled()) {
     // Store by raw target — Vue's onTrack/onTrigger events pass the raw object, not the proxy.
     reactiveCreationLocations.set(target, captureSourceLocation());
   }
   return result;
 }
 
-export function shallowRef<T>(value?: T): Ref<T> {
+export function shallowRef<T>(value?: T, options?: { label?: string }): Ref<T> {
   const result = vueShallowRef(value) as Ref<T>;
   debug.effect.registerRef({
     id: refId(result),
     kind: "shallowRef",
+    label: options?.label,
     createdAt: captureSourceLocation(),
     createdByEffectId: globalContext?.meta?.effectId,
   });
@@ -481,18 +533,63 @@ export function toRefs<T extends object>(
 
 const seenRefs = new WeakMap<Ref<unknown>, number>();
 let refIdCounter = 1;
-let infraRefIdCounter = -1;
 const effectIdMap = new WeakMap<object, number>();
 
-export function refId(ref: Ref<unknown>, isInfrastructure?: boolean): number {
+// Stable ID mapping for (reactive, key) pairs — each property acts as a virtual ref.
+const reactivePropertyIds = new WeakMap<object, Map<string | number, number>>();
+
+export function refId(ref: Ref<unknown>): number {
   let id = seenRefs.get(ref);
   if (id === undefined) {
-    id = isInfrastructure ? infraRefIdCounter-- : refIdCounter++;
+    id = refIdCounter++;
     seenRefs.set(ref, id);
   }
   return id;
 }
 
+/**
+ * Get a stable ref ID for a property of a reactive object.
+ * Each (target, key) pair gets a unique positive ID from the same counter as refs.
+ */
+export function reactivePropertyRefId(
+  target: object,
+  key: string | number,
+): number {
+  let keys = reactivePropertyIds.get(target);
+  if (!keys) {
+    keys = new Map();
+    reactivePropertyIds.set(target, keys);
+  }
+  let id = keys.get(key);
+  if (id === undefined) {
+    id = refIdCounter++;
+    keys.set(key, id);
+  }
+  return id;
+}
+
+/**
+ * Build a human-readable label for a reactive property like `symbolName.prop`.
+ */
+export function formatReactivePropertyLabel(
+  target: object,
+  key: string | number,
+): string {
+  let ownerLabel: string;
+  try {
+    const str = String(target);
+    // OutputSymbol toString() returns something like: TSOutputSymbol "MyInterface"[42]
+    // Trim to just the meaningful part
+    ownerLabel = str.length > 60 ? str.slice(0, 57) + "..." : str;
+  } catch {
+    ownerLabel = "reactive";
+  }
+  if (Array.isArray(target)) {
+    ownerLabel = "[]";
+  }
+  return `${ownerLabel}.${key}`;
+}
+
 /** Allocate a unique reactive target ID from the same counter space as ref IDs. */
 export function nextReactiveId(): number {
   return refIdCounter++;
@@ -500,7 +597,6 @@ export function nextReactiveId(): number {
 
 export function resetRefIdCounter(): void {
   refIdCounter = 1;
-  infraRefIdCounter = -1;
 }
 
 export function getEffectDebugId(effect: object): number | undefined {

package/src/render.ts

@@ -6,10 +6,17 @@ import { SourceFileContext } from "./context/source-file.js";
 import {
   debug,
   getRenderNodeId,
+  isDevtoolsConnected,
   isDevtoolsEnabled,
   type RenderTreeNodeInfo,
 } from "./debug/index.js";
-import { broadcastDevtoolsMessage } from "./devtools/devtools-server.js";
+import {
+  beginTransaction,
+  closeTrace,
+  commitTransaction,
+  notifyDiagnosticsReport,
+} from "./debug/trace-writer.js";
+import { isTraceEnabled } from "./debug/trace.js";
 import {
   attachDiagnosticsCollector,
   DiagnosticsCollector,
@@ -52,6 +59,43 @@ import { IntrinsicElement, isIntrinsicElement } from "./runtime/intrinsic.js";
 import { flushJobs, flushJobsAsync, waitForSignal } from "./scheduler.js";
 
 const notifiedErrors = new WeakSet<object>();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Deferred file printing: mark files dirty during render, print once at end
+// ─────────────────────────────────────────────────────────────────────────────
+interface DirtyFileEntry {
+  renderNode: RenderedTextTree;
+  printOptions: {
+    printWidth?: number;
+    tabWidth?: number;
+    useTabs?: boolean;
+    insertFinalNewLine?: boolean;
+  };
+  path: string;
+  filetype: string;
+}
+const dirtyFiles = new Map<string, DirtyFileEntry>();
+const lastFlushTimeByFile = new Map<string, number>();
+const DEVTOOLS_FLUSH_INTERVAL_MS = 1000;
+
+function flushDirtyFile(path: string): void {
+  const entry = dirtyFiles.get(path);
+  if (!entry) return;
+  dirtyFiles.delete(path);
+  const contents = printTree(entry.renderNode, {
+    ...entry.printOptions,
+    insertFinalNewLine: entry.printOptions.insertFinalNewLine ?? true,
+    noFlush: true,
+  });
+  debug.files.updated({ path: entry.path, filetype: entry.filetype, contents });
+}
+
+function flushDirtyFiles(): void {
+  for (const path of [...dirtyFiles.keys()]) {
+    flushDirtyFile(path);
+  }
+}
+
 let lastRenderError: {
   error: { name: string; message: string; stack?: string };
   componentStack: Array<{
@@ -275,10 +319,7 @@ function reportDiagnosticsForTree(tree: RenderedTextTree) {
   const entries = diagnostics.getDiagnostics();
   if (entries.length === 0) return;
   reportDiagnostics(diagnostics);
-  void broadcastDevtoolsMessage({
-    type: "diagnostics:report",
-    diagnostics: entries,
-  });
+  notifyDiagnosticsReport(entries);
 }
 
 // Re-export from print-hook.ts to maintain backwards compatibility
@@ -313,9 +354,13 @@ export function render(
   const tree = renderTree(children);
   flushJobs();
   const output = sourceFilesForTree(tree, options);
+  flushDirtyFiles();
   reportDiagnosticsForTree(tree);
   reportLastRenderError();
   debug.render.complete();
+  // Only close the trace DB when devtools is NOT running. When devtools is
+  // active the DB must remain open for post-render reactive updates.
+  if (isTraceEnabled() && !isDevtoolsEnabled()) closeTrace();
   if (isDevtoolsEnabled()) {
     void waitForSignal();
   }
@@ -335,9 +380,13 @@ export async function renderAsync(
   // Ensure all reactive updates are flushed before printing.
   await flushJobsAsync();
   const output = sourceFilesForTree(tree, options);
+  flushDirtyFiles();
   reportDiagnosticsForTree(tree);
   reportLastRenderError();
   debug.render.complete();
+  // Only close the trace DB when devtools is NOT running. When devtools is
+  // active the DB must remain open for post-render reactive updates.
+  if (isTraceEnabled() && !isDevtoolsEnabled()) closeTrace();
 
   return output;
 }
@@ -449,17 +498,23 @@ export function renderTree(children: Children) {
   debug.effect.reset();
   debug.symbols.reset();
   debug.files.reset();
+  dirtyFiles.clear();
+  lastFlushTimeByFile.clear();
   debug.render.initialize(rootElem);
+  if (isTraceEnabled()) beginTransaction();
   try {
     root(() => {
       attachDiagnosticsCollector(diagnostics);
       renderWorker(rootElem, children);
     });
   } catch (e) {
+    if (isTraceEnabled()) commitTransaction();
+    flushDirtyFiles();
     notifyRenderError(e);
     reportLastRenderError();
     throw e;
   }
+  if (isTraceEnabled()) commitTransaction();
 
   diagnosticsByTree.set(rootElem, diagnostics);
 
@@ -761,8 +816,12 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
       }
     } else if (isComponentCreator(child)) {
       const index = node.length;
-      const rerenderToken = isDevtoolsEnabled() ? ref(0) : undefined;
-      const breakNext = isDevtoolsEnabled() ? ref(false) : undefined;
+      const rerenderToken =
+        isDevtoolsEnabled() ? ref(0, { isInfrastructure: true }) : undefined;
+      const breakNext =
+        isDevtoolsEnabled() ?
+          ref(false, { isInfrastructure: true })
+        : undefined;
       // todo: remove this effect (only needed for context, not needed for anything else)
       effect(
         () => {
@@ -789,15 +848,21 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
             source: child.source,
             isExisting: Array.isArray(existing),
             actions: {
-              rerender: () => {
-                lastRenderError = null;
-                if (rerenderToken) rerenderToken.value++;
-              },
-              rerenderAndBreak: () => {
-                lastRenderError = null;
-                if (breakNext) breakNext.value = true;
-                if (rerenderToken) rerenderToken.value++;
-              },
+              rerender:
+                rerenderToken ?
+                  () => {
+                    lastRenderError = null;
+                    rerenderToken.value++;
+                  }
+                : () => {},
+              rerenderAndBreak:
+                breakNext && rerenderToken ?
+                  () => {
+                    lastRenderError = null;
+                    breakNext.value = true;
+                    rerenderToken.value++;
+                  }
+                : () => {},
             },
           });
           if (Array.isArray(existing)) {
@@ -809,7 +874,7 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
           let childResult: Children | undefined;
           try {
             childResult = untrack(() => {
-              const shouldBreak = breakNext?.value;
+              const shouldBreak = breakNext?.value ?? false;
               if (shouldBreak) {
                 breakNext!.value = false;
                 // eslint-disable-next-line no-debugger
@@ -927,29 +992,38 @@ function findSourceFileContext(node: RenderedTextTree) {
 }
 
 function notifyFileUpdateForNode(node: RenderedTextTree) {
-  // Only do the expensive printTree when devtools are actually enabled
-  if (!isDevtoolsEnabled()) return;
+  // Only track when devtools or trace are actually enabled
+  if (!isDevtoolsEnabled() && !isTraceEnabled()) return;
   const context = findSourceFileContext(node);
   if (!context?.meta?.sourceFile) return;
   if (context.meta.sourceFileReady === false) return;
   const sourceFile = context.meta.sourceFile;
   const renderNode: RenderedTextTree =
     (context.meta.renderNode as RenderedTextTree | undefined) ?? node;
-  // Pass noFlush here since it flushes jobs and can re-enter rendering
-  // during effect setup, triggering premature cleanup.
-  const contents = printTree(renderNode, {
-    printWidth: context.meta?.printOptions?.printWidth,
-    tabWidth: context.meta?.printOptions?.tabWidth,
-    useTabs: context.meta?.printOptions?.useTabs,
-    insertFinalNewLine: context.meta?.printOptions?.insertFinalNewLine ?? true,
-    noFlush: true,
-  });
 
-  debug.files.updated({
+  // Mark this file as dirty — defer the expensive printTree to end of render
+  dirtyFiles.set(sourceFile.path, {
+    renderNode,
+    printOptions: {
+      printWidth: context.meta?.printOptions?.printWidth,
+      tabWidth: context.meta?.printOptions?.tabWidth,
+      useTabs: context.meta?.printOptions?.useTabs,
+      insertFinalNewLine: context.meta?.printOptions?.insertFinalNewLine,
+    },
     path: sourceFile.path,
     filetype: sourceFile.filetype,
-    contents,
   });
+
+  // When a devtools client is connected, throttle file flushing to ~1s per file
+  // so the user can watch content build up during rendering.
+  if (isDevtoolsConnected()) {
+    const now = Date.now();
+    const lastFlush = lastFlushTimeByFile.get(sourceFile.path) ?? 0;
+    if (now - lastFlush >= DEVTOOLS_FLUSH_INTERVAL_MS) {
+      lastFlushTimeByFile.set(sourceFile.path, now);
+      flushDirtyFile(sourceFile.path);
+    }
+  }
 }
 
 type NormalizedChildren = NormalizedChild | NormalizedChildren[];

package/src/scheduler.ts

@@ -1,11 +1,21 @@
 import { ReactiveEffect } from "@vue/reactivity";
 import { debug } from "./debug/index.js";
+import {
+  beginTransaction,
+  commitTransaction,
+  insertEffectLifecycle,
+  insertSchedulerFlush,
+  insertSchedulerJob,
+} from "./debug/trace-writer.js";
+import { isTraceEnabled } from "./debug/trace.js";
+import { getEffectDebugId } from "./reactivity.js";
 
 export interface QueueJob {
   run(): void;
 }
 const immediateQueue = new Set<QueueJob>();
 const queue = new Set<QueueJob>();
+
 function isJobActive(job: QueueJob): boolean {
   // ReactiveEffect uses bit 0 (flags & 1) as the ACTIVE flag.
   // Skip effects that were stopped after being queued.
@@ -18,12 +28,19 @@ let resolveWaitForSignal: (() => void) | null = null;
 let jobSignalPromise: Promise<void> | null = null;
 let resolveJobSignal: (() => void) | null = null;
 
-// Maps effect debug IDs to the ref that most recently triggered them
+// Maps effect debug IDs to the ref that most recently triggered them.
+// Intentionally overwrites on repeated triggers for the same effect before flush —
+// we only need the last trigger ref for lifecycle recording, not all intermediate ones.
 const lastTriggerRef = new Map<number, number>();
 
 /**
  * Record which ref triggered an effect re-run.
  * Called from the onTrigger debug hook before the effect is scheduled.
+ *
+ * Note: if an effect is triggered multiple times before flush, only the last
+ * trigger ref is retained. This is intentional — we care about the most
+ * recent cause, and tracking all triggers would add overhead with minimal
+ * diagnostic value since only the last mutation actually caused the re-run.
  */
 export function setLastTriggerRef(effectDebugId: number, refId: number): void {
   lastTriggerRef.set(effectDebugId, refId);
@@ -52,6 +69,18 @@ export function queueJob(job: QueueJob | (() => void), immediate = false) {
     queue.add(job);
   }
 
+  if (isTraceEnabled()) {
+    const effectId = getEffectDebugId(job as object);
+    if (effectId !== undefined) {
+      insertSchedulerJob(
+        "queue",
+        effectId,
+        immediate,
+        immediateQueue.size + queue.size,
+      );
+    }
+  }
+
   if (resolveJobSignal) {
     resolveJobSignal();
     resolveJobSignal = null;
@@ -72,19 +101,69 @@ export function trackPromise(promise: Promise<any>) {
 
 export function flushJobs() {
   // First, run all synchronous jobs
+  if (isTraceEnabled()) beginTransaction();
   let job;
+  let jobCount = 0;
   while ((job = takeJob()) !== null) {
-    if (!isJobActive(job)) continue;
+    if (isTraceEnabled()) {
+      const effectId = getEffectDebugId(job as object);
+      if (effectId !== undefined) {
+        insertSchedulerJob(
+          "run",
+          effectId,
+          false,
+          immediateQueue.size + queue.size,
+        );
+      }
+    }
+    if (!isJobActive(job)) {
+      if (isTraceEnabled()) {
+        const effectId = getEffectDebugId(job as object);
+        if (effectId !== undefined) {
+          insertEffectLifecycle(
+            effectId,
+            "skipped",
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+          );
+        }
+      }
+      continue;
+    }
+    if (isTraceEnabled()) {
+      const effectId = getEffectDebugId(job as object);
+      if (effectId !== undefined) {
+        const triggerRefId = lastTriggerRef.get(effectId);
+        lastTriggerRef.delete(effectId);
+        insertEffectLifecycle(
+          effectId,
+          "ran",
+          triggerRefId,
+          undefined,
+          undefined,
+          undefined,
+        );
+      }
+    }
     job.run();
+    jobCount++;
   }
 
   // If there are no pending promises, we're done
   if (pendingPromises.size > 0) {
+    if (isTraceEnabled()) commitTransaction();
     throw new Error(
       "Asynchronous jobs were found but render was called synchronously. Use `renderAsync` instead.",
     );
   }
 
+  if (isTraceEnabled()) {
+    insertSchedulerFlush(jobCount);
+    commitTransaction();
+  }
+
   debug.render.flushJobsComplete();
 }
 
@@ -115,34 +194,74 @@ export function isWaitingForSignal() {
 
 export async function flushJobsAsync() {
   // Keep running jobs until both the queues are empty and all promises are resolved
-  while (true) {
-    // First, run all synchronous jobs
-    let job;
-    while ((job = takeJob()) !== null) {
-      if (!isJobActive(job)) continue;
-      job.run();
-    }
+  if (isTraceEnabled()) beginTransaction();
+  try {
+    while (true) {
+      // First, run all synchronous jobs
+      let job;
+      while ((job = takeJob()) !== null) {
+        if (!isJobActive(job)) {
+          if (isTraceEnabled()) {
+            const effectId = getEffectDebugId(job as object);
+            if (effectId !== undefined) {
+              insertEffectLifecycle(
+                effectId,
+                "skipped",
+                undefined,
+                undefined,
+                undefined,
+                undefined,
+              );
+            }
+          }
+          continue;
+        }
+        if (isTraceEnabled()) {
+          const effectId = getEffectDebugId(job as object);
+          if (effectId !== undefined) {
+            const triggerRefId = lastTriggerRef.get(effectId);
+            lastTriggerRef.delete(effectId);
+            insertEffectLifecycle(
+              effectId,
+              "ran",
+              triggerRefId,
+              undefined,
+              undefined,
+              undefined,
+            );
+          }
+        }
+        job.run();
+      }
 
-    // If there are no pending promises, we're done
-    if (pendingPromises.size === 0) {
-      break;
-    }
+      // If there are no pending promises, we're done
+      if (pendingPromises.size === 0) {
+        break;
+      }
 
-    if (!jobSignalPromise) {
-      jobSignalPromise = new Promise<void>((resolve) => {
-        resolveJobSignal = resolve;
-      });
-    }
+      // Commit before awaiting so writes are visible, then re-open after
+      if (isTraceEnabled()) commitTransaction();
 
-    // Wait for either pending promises to complete or new jobs to arrive
-    await Promise.race([
-      Promise.allSettled(Array.from(pendingPromises)),
-      jobSignalPromise,
-    ]);
+      if (!jobSignalPromise) {
+        jobSignalPromise = new Promise<void>((resolve) => {
+          resolveJobSignal = resolve;
+        });
+      }
 
-    // Clear the job signal after each iteration so we create a new one next time
-    jobSignalPromise = null;
-    resolveJobSignal = null;
+      // Wait for either pending promises to complete or new jobs to arrive
+      await Promise.race([
+        Promise.allSettled(Array.from(pendingPromises)),
+        jobSignalPromise,
+      ]);
+
+      // Clear the job signal after each iteration so we create a new one next time
+      jobSignalPromise = null;
+      resolveJobSignal = null;
+
+      if (isTraceEnabled()) beginTransaction();
+    }
+  } finally {
+    if (isTraceEnabled()) commitTransaction();
   }
 
   debug.render.flushJobsComplete();