@alloy-js/core 0.23.0-dev.8 → 0.23.0

package/src/render-stack.ts

@@ -2,6 +2,7 @@ import pc from "picocolors";
 import { contextsByKey } from "./context.js";
 import { SourceDirectoryContext } from "./context/source-directory.js";
 import { SourceFileContext } from "./context/source-file.js";
+import { cwd } from "./host/node-host.js";
 import { Context, getContext } from "./reactivity.js";
 import { Component, Props, SourceLocation } from "./runtime/component.js";
 
@@ -33,6 +34,11 @@ export function popStack() {
   renderStack.pop();
 }
 
+export function currentComponentName(): string | undefined {
+  const entry = renderStack[renderStack.length - 1];
+  return entry?.component.name || undefined;
+}
+
 export function clearRenderStack() {
   renderStack.length = 0;
 }
@@ -120,12 +126,12 @@ function formatValue(value: unknown): string {
 }
 
 function formatSourceLocation(source: SourceLocation): string {
-  const cwd = process.cwd();
+  const currentCwd = cwd();
   let filePath = source.fileName;
 
   // Convert to relative path if under cwd
-  if (filePath.startsWith(cwd)) {
-    filePath = filePath.slice(cwd.length + 1); // +1 to remove leading slash
+  if (currentCwd && filePath.startsWith(currentCwd)) {
+    filePath = filePath.slice(currentCwd.length + 1); // +1 to remove leading slash
   }
 
   return `${filePath}:${source.lineNumber}:${source.columnNumber}`;

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<{
@@ -238,12 +282,14 @@ const {
 
 export interface OutputDirectory {
   kind: "directory";
+  /** Full path from the output root, e.g. `"generated-client/src"`. Do not prepend parent directory paths when walking the tree. */
   path: string;
   contents: (OutputDirectory | OutputFile)[];
 }
 
 export interface OutputFileBase {
   kind: "file";
+  /** Full path from the output root, e.g. `"generated-client/src/models.ext"`. Do not prepend parent directory paths when walking the tree. */
   path: string;
 }
 
@@ -275,10 +321,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 +356,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 +382,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 +500,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);
 
@@ -498,11 +555,12 @@ export function notifyContentState() {
     const startContext = getContext()!;
 
     if (startContext.childrenWithContent === 0) {
-      if (startContext.isEmpty!.value === true) {
+      if (startContext._lastEmpty) {
         // it was already empty, no work to do.
         return;
       }
 
+      startContext._lastEmpty = true;
       if (startContext.isEmpty) {
         startContext.isEmpty.value = true;
       }
@@ -518,18 +576,20 @@ export function notifyContentState() {
           // This isn't the last content so we have no work to do
           break;
         }
+        current._lastEmpty = true;
         if (current.isEmpty) {
           current.isEmpty.value = true;
         }
         current = current.owner;
       }
     } else {
-      if (startContext.isEmpty!.value === false) {
+      if (!startContext._lastEmpty) {
         // it was already non-empty, no work to do.
         return;
       }
 
-      if (startContext.isEmpty && startContext.isEmpty.value) {
+      startContext._lastEmpty = false;
+      if (startContext.isEmpty) {
         startContext.isEmpty.value = false;
       }
 
@@ -542,7 +602,8 @@ export function notifyContentState() {
           break;
         }
 
-        if (current.isEmpty && current.isEmpty.value) {
+        current._lastEmpty = false;
+        if (current.isEmpty) {
           current.isEmpty.value = false;
         }
 
@@ -757,16 +818,19 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
       }
     } else if (isComponentCreator(child)) {
       const index = node.length;
-      const rerenderToken = ref(0);
-      const breakNext = ref(false);
+      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(
         () => {
           // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-          rerenderToken.value;
+          rerenderToken?.value;
           const context = getContext();
           context!.childrenWithContent = 0;
-          context!.isEmpty ??= ref(true);
 
           if (context) context.componentOwner = child;
           const existing = node[index];
@@ -786,15 +850,21 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
             source: child.source,
             isExisting: Array.isArray(existing),
             actions: {
-              rerender: () => {
-                lastRenderError = null;
-                rerenderToken.value++;
-              },
-              rerenderAndBreak: () => {
-                lastRenderError = null;
-                breakNext.value = true;
-                rerenderToken.value++;
-              },
+              rerender:
+                rerenderToken ?
+                  () => {
+                    lastRenderError = null;
+                    rerenderToken.value++;
+                  }
+                : () => {},
+              rerenderAndBreak:
+                breakNext && rerenderToken ?
+                  () => {
+                    lastRenderError = null;
+                    breakNext.value = true;
+                    rerenderToken.value++;
+                  }
+                : () => {},
             },
           });
           if (Array.isArray(existing)) {
@@ -806,9 +876,9 @@ 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;
+                breakNext!.value = false;
                 // eslint-disable-next-line no-debugger
                 debugger;
               }
@@ -880,7 +950,6 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
           }
           const context = getContext();
           context!.childrenWithContent = 0;
-          context!.isEmpty ??= ref(true);
 
           const existing = node[index];
           const memoNode: RenderedTextTree =
@@ -925,29 +994,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,22 +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
@@ -30,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;
@@ -50,18 +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 (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();
 }
 
@@ -92,33 +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) {
-      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();

package/src/symbols/output-scope.ts

@@ -1,7 +1,6 @@
 import {
   reactive,
   ReactiveFlags,
-  shallowReactive,
   track,
   TrackOpTypes,
   trigger,
@@ -10,7 +9,7 @@ import {
 import type { Binder } from "../binder.js";
 import { useBinder } from "../context/binder.js";
 import { inspect } from "../inspect.js";
-import { effect, untrack } from "../reactivity.js";
+import { effect, shallowReactive, untrack } from "../reactivity.js";
 import { OutputDeclarationSpace, OutputSpace } from "./output-space.js";
 import { OutputSymbol } from "./output-symbol.js";
 
@@ -55,6 +54,11 @@ export interface OutputScopeOptions {
  * within a reactive context.
  */
 export abstract class OutputScope {
+  /**
+   * The declaration space keys for this scope type. Subclasses override this
+   * to declare which declaration spaces are created on construction (e.g.,
+   * `["types", "values"]`).
+   */
   static readonly declarationSpaces: Readonly<string[]> = [] as const;
 
   #name: string;
@@ -126,7 +130,8 @@ export abstract class OutputScope {
   #spaces: Record<string, OutputDeclarationSpace>;
 
   /**
-   * Get the declaration space for the given key.
+   * Get the declaration space for the given key (e.g., `"types"`, `"values"`).
+   * Returns `undefined` when no space with that key exists on this scope.
    */
   spaceFor(key: string): OutputSpace | undefined {
     return this.#spaces[key];
@@ -154,6 +159,32 @@ export abstract class OutputScope {
 
   [ReactiveFlags.SKIP] = true;
 
+  /**
+   * Subclasses must forward all three positional arguments to `super`. See
+   * {@link createScope} for the preferred instantiation path.
+   *
+   * @param name - A descriptive name for this scope (used in debugging and
+   * diagnostics).
+   * @param parentScope - The parent scope in the scope tree, or `undefined`
+   * for root scopes. Inside a component, obtain this via `useScope()`.
+   * @param options - Additional scope options; see {@link OutputScopeOptions}.
+   *
+   * @example
+   * ```ts
+   * class MyScope extends OutputScope {
+   *   constructor(
+   *     name: string,
+   *     parent: OutputScope | undefined,
+   *     options?: OutputScopeOptions,
+   *   ) {
+   *     super(name, parent, options);
+   *   }
+   * }
+   *
+   * // Inside a component:
+   * const scope = createScope(MyScope, "my-scope", useScope());
+   * ```
+   */
   constructor(
     name: string,
     parentScope: OutputScope | undefined,

package/src/symbols/output-space.ts

@@ -5,7 +5,16 @@ import { OutputScope } from "./output-scope.js";
 import { OutputSymbol } from "./output-symbol.js";
 import { SymbolTable } from "./symbol-table.js";
 
+/**
+ * A symbol table that belongs to either a scope (declaration space) or a symbol
+ * (member space).
+ */
 export type OutputSpace = OutputDeclarationSpace | OutputMemberSpace;
+
+/**
+ * A symbol table attached to an {@link OutputScope}. Holds lexical declarations
+ * visible within that scope (e.g., "types" or "values" in a TypeScript module).
+ */
 export class OutputDeclarationSpace extends SymbolTable {
   constructor(scope: OutputScope, key: string, binder?: Binder) {
     super(key, binder);
@@ -27,6 +36,10 @@ export class OutputDeclarationSpace extends SymbolTable {
   }
 }
 
+/**
+ * A symbol table attached to an {@link OutputSymbol}. Holds member declarations
+ * belonging to that symbol (e.g., "static" or "instance" members of a class).
+ */
 export class OutputMemberSpace extends SymbolTable {
   constructor(symbol: OutputSymbol, key: string, binder?: Binder) {
     super(key, binder);