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

package/src/resource.ts

@@ -101,26 +101,35 @@ export function createResource<T, U>(
         }),
     );
   } else {
-    effect(() => {
-      let input: T;
-      if (isRef(getter)) {
-        input = getter.value;
-      } else {
-        input = getter();
-      }
-      const promise = (fetcher as (input: T) => Promise<U>)(input);
-      trackPromise(promise);
-      promise.then(
-        (result) => {
-          resource.data = result;
-          resource.loading = false;
-        },
-        (error) => {
-          resource.error = error;
-          resource.loading = false;
+    effect(
+      () => {
+        let input: T;
+        if (isRef(getter)) {
+          input = getter.value;
+        } else {
+          input = getter();
+        }
+        const promise = (fetcher as (input: T) => Promise<U>)(input);
+        trackPromise(promise);
+        promise.then(
+          (result) => {
+            resource.data = result;
+            resource.loading = false;
+          },
+          (error) => {
+            resource.error = error;
+            resource.loading = false;
+          },
+        );
+      },
+      undefined,
+      {
+        debug: {
+          name: "resource:fetch",
+          type: "resource",
         },
-      );
-    });
+      },
+    );
   }
 
   return resource;

package/src/scheduler.ts

@@ -1,17 +1,61 @@
 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.
+  const flags = (job as any).flags;
+  return flags === undefined || (flags & 1) !== 0;
+}
 const pendingPromises = new Set<Promise<any>>();
+let waitForSignalPromise: Promise<void> | null = null;
+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.
+// 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);
+}
 
 export function scheduler(immediate = false) {
+  if (!immediate) return defaultScheduler;
   return function (this: ReactiveEffect) {
-    queueJob(this, immediate);
+    queueJob(this, true);
   };
 }
+
+const defaultScheduler = function (this: ReactiveEffect) {
+  queueJob(this, false);
+};
 export function queueJob(job: QueueJob | (() => void), immediate = false) {
   // if we have an immediate job, we don't need to queue the normal job.
   // the set is serving an important purpose here in deduping the effects we run
@@ -19,12 +63,29 @@ export function queueJob(job: QueueJob | (() => void), immediate = false) {
   if (typeof job === "function") {
     job = { run: job };
   }
-
   if (immediate) {
     immediateQueue.add(job);
   } else {
     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;
+    jobSignalPromise = null;
+  }
 }
 
 /**
@@ -40,36 +101,170 @@ 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 (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();
+}
+
+export function waitForSignal(): Promise<void> {
+  if (!waitForSignalPromise) {
+    waitForSignalPromise = new Promise<void>((resolve) => {
+      resolveWaitForSignal = resolve;
+    });
+    pendingPromises.add(waitForSignalPromise);
+  }
+  return waitForSignalPromise;
+}
+
+export function signalSchedulerWait() {
+  if (resolveWaitForSignal) {
+    resolveWaitForSignal();
+    resolveWaitForSignal = null;
+  }
+  if (waitForSignalPromise) {
+    pendingPromises.delete(waitForSignalPromise);
+  }
+  waitForSignalPromise = null;
+}
+
+export function isWaitingForSignal() {
+  return waitForSignalPromise !== null;
 }
 
 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) {
-      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;
+      }
+
+      // Commit before awaiting so writes are visible, then re-open after
+      if (isTraceEnabled()) commitTransaction();
+
+      if (!jobSignalPromise) {
+        jobSignalPromise = new Promise<void>((resolve) => {
+          resolveJobSignal = resolve;
+        });
+      }
 
-    // Wait for all current promises to complete
-    await Promise.allSettled(Array.from(pendingPromises));
+      // 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();
 }
 
 function takeJob() {

package/src/symbols/basic-symbol.ts

@@ -1,3 +1,4 @@
+import { createSymbol } from "../binder.js";
 import { OutputSymbol } from "./output-symbol.js";
 
 /**
@@ -16,7 +17,11 @@ export class BasicSymbol extends OutputSymbol {
 
   copy() {
     const options = this.getCopyOptions();
-    const copiedSymbol = new BasicSymbol(this.name, undefined, options);
+    const binder = this.binder;
+    const copiedSymbol = createSymbol(BasicSymbol, this.name, undefined, {
+      ...options,
+      binder,
+    });
     this.initializeCopy(copiedSymbol);
 
     return copiedSymbol;

package/src/symbols/decl.ts

@@ -1,4 +1,5 @@
 import { toRef } from "@vue/reactivity";
+import { createSymbol } from "../binder.js";
 import { useScope } from "../context/scope.js";
 import { Namekey } from "../refkey.js";
 import { createComponent } from "../runtime/component.js";
@@ -18,7 +19,10 @@ export function decl(namekey: Namekey) {
         `Cannot declare symbol in non-basic scope: ${currentScope.constructor.name}. Use a language-specific 'decl' function instead.`,
       );
     }
-    const symbol = new BasicSymbol(namekey, currentScope.symbols);
+    const binder = currentScope.binder;
+    const symbol = createSymbol(BasicSymbol, namekey, currentScope.symbols, {
+      binder,
+    });
 
     return toRef(symbol, "name");
   }, {});

package/src/symbols/output-scope.ts

@@ -1,8 +1,6 @@
 import {
-  effect,
   reactive,
   ReactiveFlags,
-  shallowReactive,
   track,
   TrackOpTypes,
   trigger,
@@ -11,8 +9,7 @@ import {
 import type { Binder } from "../binder.js";
 import { useBinder } from "../context/binder.js";
 import { inspect } from "../inspect.js";
-import { untrack } from "../reactivity.js";
-import { formatScope, trace, traceEffect, TracePhase } from "../tracer.js";
+import { effect, shallowReactive, untrack } from "../reactivity.js";
 import { OutputDeclarationSpace, OutputSpace } from "./output-space.js";
 import { OutputSymbol } from "./output-symbol.js";
 
@@ -154,7 +151,7 @@ export abstract class OutputScope {
     return this.#binder;
   }
 
-  [ReactiveFlags.SKIP] = this;
+  [ReactiveFlags.SKIP] = true;
 
   constructor(
     name: string,
@@ -167,9 +164,20 @@ export abstract class OutputScope {
     this.#binder = options.binder ?? useBinder();
     this.#children = shallowReactive(new Set());
     this.#parent = parentScope;
-    effect(() => {
-      this.#setOwnerSymbol(options.ownerSymbol?.movedTo ?? options.ownerSymbol);
-    });
+    effect(
+      () => {
+        this.#setOwnerSymbol(
+          options.ownerSymbol?.movedTo ?? options.ownerSymbol,
+        );
+      },
+      undefined,
+      {
+        debug: {
+          name: "outputScope:ownerSymbol",
+          type: "symbol",
+        },
+      },
+    );
 
     if (this.#parent) {
       this.#parent.children.add(this);
@@ -184,12 +192,8 @@ export abstract class OutputScope {
       ]),
     );
 
+    // Notify binder so resolution tracking works even without createScope
     this.#binder?.notifyScopeCreated(this);
-
-    trace(TracePhase.scope.create, () => `${formatScope(this)}`);
-    traceEffect(TracePhase.scope.update, () => {
-      return `${formatScope(this)}`;
-    });
   }
 
   /**
@@ -215,6 +219,10 @@ export abstract class OutputScope {
     return this.#ownerSymbol;
   }
 
+  get debugInfo(): Record<string, unknown> {
+    return {};
+  }
+
   #setOwnerSymbol(value: OutputSymbol | undefined) {
     const old = this.#ownerSymbol;
     this.#ownerSymbol = value;

package/src/symbols/output-symbol.ts

@@ -3,7 +3,6 @@ import {
   reactive,
   ReactiveFlags,
   Ref,
-  shallowReactive,
   track,
   TrackOpTypes,
   trigger,
@@ -12,17 +11,19 @@ import {
 } from "@vue/reactivity";
 import type { Binder } from "../binder.js";
 import { useBinder } from "../context/binder.js";
+import { debug, TracePhase } from "../debug/index.js";
 import { inspect } from "../inspect.js";
 import { NamePolicyGetter } from "../name-policy.js";
-import { untrack } from "../reactivity.js";
-import { Namekey, type Refkey } from "../refkey.js";
+import { shallowReactive, untrack } from "../reactivity.js";
 import {
-  formatSymbol,
-  formatSymbolName,
-  trace,
-  traceEffect,
-  TracePhase,
-} from "../tracer.js";
+  isMemberRefkey,
+  isNamekey,
+  isSymbolRefkey,
+  Namekey,
+  toRefkey,
+  type Refkey,
+} from "../refkey.js";
+import { formatSymbolName } from "../tracer.js";
 import {
   OutputDeclarationSpace,
   OutputMemberSpace,
@@ -459,6 +460,10 @@ export abstract class OutputSymbol {
     return this.#isTyped;
   }
 
+  get debugInfo(): Record<string, unknown> {
+    return {};
+  }
+
   #namePolicy: NamePolicyGetter | undefined;
   get namePolicy() {
     return this.#namePolicy;
@@ -552,10 +557,7 @@ export abstract class OutputSymbol {
       ]),
     );
 
-    trace(TracePhase.symbol.create, () => `${formatSymbol(this)}`);
-    traceEffect(TracePhase.symbol.update, () => {
-      return `${formatSymbol(this)}`;
-    });
+    // Notify binder so resolution tracking works even without createSymbol
     this.#binder?.notifySymbolCreated(this);
   }
 
@@ -570,7 +572,7 @@ export abstract class OutputSymbol {
   }
 
   delete() {
-    trace(TracePhase.symbol.delete, () => `${formatSymbolName(this)}`);
+    debug.trace(TracePhase.symbol.delete, () => `${formatSymbolName(this)}`);
     if (this.#spaces) {
       this.#spaces.forEach((space) => space.delete(this));
     }
@@ -677,3 +679,21 @@ export abstract class OutputSymbol {
     return untrack(() => `${this.constructor.name} "${this.name}"[${this.id}]`);
   }
 }
+
+function _formatRefkey(refkey: Refkey): string {
+  if (isNamekey(refkey)) {
+    return `name:${refkey.name}`;
+  }
+  if (isMemberRefkey(refkey)) {
+    const base = _formatRefkey(toRefkey(refkey.base));
+    const member =
+      typeof refkey.member === "string" ?
+        refkey.member
+      : _formatRefkey(toRefkey(refkey.member));
+    return `member:${base}.${member}`;
+  }
+  if (isSymbolRefkey(refkey)) {
+    return `key:${refkey.key}`;
+  }
+  return "refkey";
+}

package/src/symbols/symbol-flow.ts

@@ -1,9 +1,16 @@
-import { isRef, Ref, shallowReactive } from "@vue/reactivity";
-import { Context, effect, getContext, onCleanup } from "../reactivity.js";
+import { isRef, Ref } from "@vue/reactivity";
+import {
+  Context,
+  effect,
+  getContext,
+  onCleanup,
+  shallowReactive,
+} from "../reactivity.js";
 
 import { MemberContext } from "../context/member-scope.js";
 import { ScopeContext } from "../context/scope.js";
-import { formatSymbolName, trace, TracePhase } from "../tracer.js";
+import { debug, TracePhase } from "../debug/index.js";
+import { formatSymbolName } from "../tracer.js";
 import { OutputSymbol } from "./output-symbol.js";
 
 export interface TakeSymbolCallback {
@@ -19,16 +26,25 @@ export function takeSymbols(cb?: (symbol: OutputSymbol) => void) {
   context.takesSymbols = true;
   context.takenSymbols = shallowReactive(new Set<OutputSymbol>());
   if (cb) {
-    effect<Set<OutputSymbol>>((oldSymbols) => {
-      for (const symbol of context.takenSymbols!) {
-        if (oldSymbols && oldSymbols.has(symbol)) {
-          continue;
+    effect<Set<OutputSymbol>>(
+      (oldSymbols) => {
+        for (const symbol of context.takenSymbols!) {
+          if (oldSymbols && oldSymbols.has(symbol)) {
+            continue;
+          }
+          cb(symbol);
         }
-        cb(symbol);
-      }
 
-      return new Set(context.takenSymbols!);
-    });
+        return new Set(context.takenSymbols!);
+      },
+      undefined,
+      {
+        debug: {
+          name: "symbolFlow:takeSymbols",
+          type: "symbol",
+        },
+      },
+    );
   }
   return context.takenSymbols;
 }
@@ -37,9 +53,9 @@ export function emitSymbol(
   symbol: OutputSymbol | Ref<OutputSymbol | undefined>,
 ) {
   if (isRef(symbol)) {
-    trace(TracePhase.symbol.flow, () => `Emitting ref to symbol`);
+    debug.trace(TracePhase.symbol.flow, () => `Emitting ref to symbol`);
   } else {
-    trace(
+    debug.trace(
       TracePhase.symbol.flow,
       () => `Emitting symbol ${formatSymbolName(symbol)}`,
     );
@@ -58,7 +74,7 @@ export function emitSymbol(
       (context.context[ScopeContext.id] || context.context[MemberContext.id])
     ) {
       // don't cross scope boundaries.
-      trace(
+      debug.trace(
         TracePhase.symbol.flow,
         () => `Not emitting symbol across scope boundary`,
       );
@@ -69,27 +85,39 @@ export function emitSymbol(
   }
 
   if (!symbolTaker) {
-    trace(TracePhase.symbol.flow, () => `No symbol taker found, not emitting`);
+    debug.trace(
+      TracePhase.symbol.flow,
+      () => `No symbol taker found, not emitting`,
+    );
     return;
   }
 
   if (isRef(symbol)) {
-    effect<OutputSymbol | undefined>((prevSymbol) => {
-      onCleanup(() => {
-        if (symbol.value) {
-          symbolTaker.takenSymbols!.delete(symbol.value);
+    effect<OutputSymbol | undefined>(
+      (prevSymbol) => {
+        onCleanup(() => {
+          if (symbol.value) {
+            symbolTaker.takenSymbols!.delete(symbol.value);
+          }
+        });
+        if (symbol.value === undefined) {
+          symbolTaker.takenSymbols!.delete(prevSymbol!);
+          return undefined;
+        } else {
+          symbolTaker.takenSymbols!.add(symbol.value);
+          return symbol.value;
         }
-      });
-      if (symbol.value === undefined) {
-        symbolTaker.takenSymbols!.delete(prevSymbol!);
-        return undefined;
-      } else {
-        symbolTaker.takenSymbols!.add(symbol.value);
-        return symbol.value;
-      }
-    });
+      },
+      undefined,
+      {
+        debug: {
+          name: "symbolFlow:emitRef",
+          type: "symbol",
+        },
+      },
+    );
   } else {
-    trace(
+    debug.trace(
       TracePhase.symbol.flow,
       () =>
         `Emitting symbol ${formatSymbolName(symbol)} taken by ${symbolTaker.componentOwner?.name ?? "unknown component"}`,
@@ -103,19 +131,28 @@ export function emitSymbol(
 
 export function moveTakenMembersTo(baseSymbol: OutputSymbol) {
   const taken = takeSymbols();
-  effect(() => {
-    for (const symbol of taken) {
-      if (symbol.isTransient) {
-        symbol.moveMembersTo(baseSymbol);
-      }
+  effect(
+    () => {
+      for (const symbol of taken) {
+        if (symbol.isTransient) {
+          symbol.moveMembersTo(baseSymbol);
+        }
 
-      for (const refkey of symbol.refkeys) {
-        if (!baseSymbol.refkeys.includes(refkey)) {
-          baseSymbol.refkeys.push(refkey);
+        for (const refkey of symbol.refkeys) {
+          if (!baseSymbol.refkeys.includes(refkey)) {
+            baseSymbol.refkeys.push(refkey);
+          }
         }
       }
-    }
-  });
+    },
+    undefined,
+    {
+      debug: {
+        name: "symbolFlow:moveTakenMembers",
+        type: "symbol",
+      },
+    },
+  );
 }
 
 export function instantiateTakenMembersTo(