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

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,44 @@
 import { ReactiveEffect } from "@vue/reactivity";
+import { debug } from "./debug/index.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
+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.
+ */
+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 +46,17 @@ 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 (resolveJobSignal) {
+    resolveJobSignal();
+    resolveJobSignal = null;
+    jobSignalPromise = null;
+  }
 }
 
 /**
@@ -42,6 +74,7 @@ export function flushJobs() {
   // First, run all synchronous jobs
   let job;
   while ((job = takeJob()) !== null) {
+    if (!isJobActive(job)) continue;
     job.run();
   }
 
@@ -51,6 +84,33 @@ export function flushJobs() {
       "Asynchronous jobs were found but render was called synchronously. Use `renderAsync` instead.",
     );
   }
+
+  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() {
@@ -59,6 +119,7 @@ export async function flushJobsAsync() {
     // First, run all synchronous jobs
     let job;
     while ((job = takeJob()) !== null) {
+      if (!isJobActive(job)) continue;
       job.run();
     }
 
@@ -67,9 +128,24 @@ export async function flushJobsAsync() {
       break;
     }
 
-    // Wait for all current promises to complete
-    await Promise.allSettled(Array.from(pendingPromises));
+    if (!jobSignalPromise) {
+      jobSignalPromise = new Promise<void>((resolve) => {
+        resolveJobSignal = resolve;
+      });
+    }
+
+    // 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;
   }
+
+  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(

package/src/symbols/symbol-slot.test.tsx

@@ -0,0 +1,41 @@
+import { shallowRef } from "@vue/reactivity";
+import { expect, it } from "vitest";
+import { renderTree } from "../render.js";
+import { flushJobs } from "../scheduler.js";
+import { BasicSymbol } from "./basic-symbol.js";
+import { emitSymbol } from "./symbol-flow.js";
+import { createSymbolSlot } from "./symbol-slot.jsx";
+
+it("captures firstSymbol", async () => {
+  const Slot = createSymbolSlot();
+
+  renderTree(
+    <Slot>
+      {() => {
+        emitSymbol(new BasicSymbol("a", undefined));
+      }}
+    </Slot>,
+  );
+  await flushJobs();
+  expect(Slot.firstSymbol.value).toBeDefined();
+  expect(Slot.firstSymbol.value!.name).toBe("a");
+});
+
+it("captures firstSymbol when emitting a ref to a symbol", async () => {
+  const Slot = createSymbolSlot();
+  const symref = shallowRef<BasicSymbol | undefined>();
+
+  renderTree(
+    <Slot>
+      {() => {
+        emitSymbol(symref);
+      }}
+    </Slot>,
+  );
+  await flushJobs();
+  expect(Slot.firstSymbol.value).toBeUndefined();
+  symref.value = new BasicSymbol("a", undefined);
+  await flushJobs();
+  expect(Slot.firstSymbol.value).toBeDefined();
+  expect(Slot.firstSymbol.value!.name).toBe("a");
+});

package/src/symbols/symbol-slot.tsx

@@ -50,36 +50,63 @@ export function createSymbolSlot(): SymbolSlot {
   Object.defineProperty(SymbolSlot, "firstSymbol", {
     get() {
       const ref = shallowRef();
-      effect(() => {
-        ref.value = symbolSlotRef.value?.values().next().value;
-      });
+      effect(
+        () => {
+          ref.value = symbolSlotRef.value?.values().next().value;
+        },
+        undefined,
+        {
+          debug: {
+            name: "symbolSlot:firstSymbol",
+            type: "symbol",
+          },
+        },
+      );
       return ref;
     },
   });
 
   SymbolSlot.copyMembersTo = (baseSymbol: OutputSymbol) => {
-    effect(() => {
-      if (!symbolSlotRef.value) {
-        return;
-      }
+    effect(
+      () => {
+        if (!symbolSlotRef.value) {
+          return;
+        }
 
-      for (const symbol of symbolSlotRef.value) {
-        symbol.copyMembersTo(baseSymbol);
-      }
-    });
+        for (const symbol of symbolSlotRef.value) {
+          symbol.copyMembersTo(baseSymbol);
+        }
+      },
+      undefined,
+      {
+        debug: {
+          name: "symbolSlot:copyMembers",
+          type: "symbol",
+        },
+      },
+    );
   };
 
   SymbolSlot.moveMembersTo = (baseSymbol: OutputSymbol) => {
-    effect(() => {
-      if (!symbolSlotRef.value) {
-        return;
-      }
-      for (const symbol of symbolSlotRef.value) {
-        if (symbol.isTransient) {
-          symbol.moveMembersTo(baseSymbol);
+    effect(
+      () => {
+        if (!symbolSlotRef.value) {
+          return;
         }
-      }
-    });
+        for (const symbol of symbolSlotRef.value) {
+          if (symbol.isTransient) {
+            symbol.moveMembersTo(baseSymbol);
+          }
+        }
+      },
+      undefined,
+      {
+        debug: {
+          name: "symbolSlot:moveMembers",
+          type: "symbol",
+        },
+      },
+    );
   };
 
   return SymbolSlot as any;