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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.23.0-dev.11",
+  "version": "0.23.0-dev.13",
   "description": "",
   "repository": {
     "type": "git",
@@ -10,35 +10,45 @@
   "exports": {
     ".": {
       "browser": "./dist/src/index.browser.js",
+      "development": "./dist/dev/src/index.js",
       "import": "./dist/src/index.js"
     },
     "./jsx-runtime": {
       "types": "./dist/src/jsx-runtime.d.ts",
+      "development": "./dist/dev/src/jsx-runtime.js",
       "import": "./dist/src/jsx-runtime.js"
     },
     "./testing": {
+      "development": "./dist/dev/testing/index.js",
       "import": "./dist/testing/index.js"
     },
     "./testing/matchers": {
       "types": "./testing/vitest.d.ts"
     },
     "./stc": {
+      "development": "./dist/dev/src/components/stc/index.js",
       "import": "./dist/src/components/stc/index.js"
     },
     "./components": {
+      "development": "./dist/dev/src/components/index.js",
       "import": "./dist/src/components/index.js"
     },
     "./devtools": {
       "types": "./dist/src/devtools-entry.d.ts",
       "browser": "./dist/src/devtools-entry.browser.js",
+      "development": "./dist/dev/src/devtools-entry.js",
       "import": "./dist/src/devtools-entry.js"
     }
   },
   "browser": {
     "./dist/src/host/alloy-host.js": "./dist/src/host/alloy-host.browser.js",
     "./src/host/alloy-host.ts": "./src/host/alloy-host.browser.ts",
+    "./dist/src/host/node-host.js": "./dist/src/host/node-host.browser.js",
+    "./src/host/node-host.ts": "./src/host/node-host.browser.ts",
     "./dist/src/inspect.js": "./dist/src/inspect.browser.js",
     "./src/inspect.ts": "./src/inspect.browser.ts",
+    "./dist/src/debug/source-map.js": "./dist/src/debug/source-map.browser.js",
+    "./src/debug/source-map.ts": "./src/debug/source-map.browser.ts",
     "./dist/src/devtools/devtools-server.js": "./dist/src/devtools/devtools-server.browser.js",
     "./src/devtools/devtools-server.ts": "./src/devtools/devtools-server.browser.ts"
   },
@@ -56,7 +66,7 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.4",
     "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
@@ -68,7 +78,7 @@
   "type": "module",
   "scripts": {
     "generate-docs": "api-extractor run",
-    "build": "alloy build && pnpm run generate-docs",
+    "build": "alloy build --with-dev && pnpm run generate-docs",
     "clean": "rimraf dist/ .temp/",
     "test": "vitest run",
     "test:watch": "vitest -w",

package/src/debug/cli.ts

@@ -1,6 +1,7 @@
 import Table from "cli-table3";
 import pc from "picocolors";
 import { contextsByKey } from "../context.js";
+import { stdoutWrite } from "../host/node-host.js";
 import { getContext, untrack } from "../reactivity.js";
 import { isReactiveTarget } from "./effects.js";
 
@@ -143,7 +144,7 @@ export function debugStack() {
         currentContext.componentOwner &&
         currentContext.componentOwner.component.name !== "Provider"
       ) {
-        process.stdout.write(
+        stdoutWrite(
           style.component.name(currentContext.componentOwner.component.name) +
             "\n",
         );
@@ -164,7 +165,7 @@ export function debugStack() {
           : pc.gray("(none)"),
         ]);
 
-        process.stdout.write(table.toString() + "\n\n");
+        stdoutWrite(table.toString() + "\n\n");
         foundContexts = [];
       }
 

package/src/debug/effects.ts

@@ -4,6 +4,7 @@ import {
   getReactiveCreationLocation,
   nextReactiveId,
 } from "../reactivity.js";
+import { loadSourceMapSupport, resolveSourceMap } from "./source-map.js";
 import { insertEdge, insertEffect, insertRef } from "./trace-writer.js";
 import {
   isDebugEnabled,
@@ -112,68 +113,6 @@ const VUE_REACTIVITY_MARKERS = [
 // Fast source location capture using V8 structured CallSite API
 // ─────────────────────────────────────────────────────────────────────────────
 
-// Lazily loaded findSourceMap from node:module
-let findSourceMap:
-  | ((path: string) =>
-      | {
-          findEntry: (
-            line: number,
-            col: number,
-          ) =>
-            | {
-                originalSource: string;
-                originalLine: number;
-                originalColumn: number;
-              }
-            | undefined;
-        }
-      | undefined)
-  | undefined;
-let findSourceMapLoaded = false;
-let realpathSync: ((path: string) => string) | undefined;
-// Cache realpath lookups to avoid repeated fs calls
-const realpathCache = new Map<string, string>();
-
-function loadFindSourceMap() {
-  if (findSourceMapLoaded) return;
-  findSourceMapLoaded = true;
-  // process.getBuiltinModule works in both ESM and CJS contexts
-  try {
-    const mod = process.getBuiltinModule?.("node:module") as
-      | typeof import("node:module")
-      | undefined;
-    if (mod && typeof mod.findSourceMap === "function") {
-      findSourceMap = mod.findSourceMap as typeof findSourceMap;
-    }
-  } catch {
-    // not available
-  }
-  try {
-    const fs = process.getBuiltinModule?.("node:fs") as
-      | typeof import("node:fs")
-      | undefined;
-    if (fs) {
-      realpathSync = fs.realpathSync;
-    }
-  } catch {
-    // not available
-  }
-}
-
-function getRealPath(fileName: string): string {
-  if (!realpathSync) return fileName;
-  let real = realpathCache.get(fileName);
-  if (real === undefined) {
-    try {
-      real = realpathSync(fileName);
-    } catch {
-      real = fileName;
-    }
-    realpathCache.set(fileName, real);
-  }
-  return real;
-}
-
 function isSkipFile(fileName: string): boolean {
   for (const skip of STACK_SKIP) {
     if (fileName.includes(skip)) return true;
@@ -188,25 +127,6 @@ function isVueReactivityFile(fileName: string): boolean {
   return false;
 }
 
-function resolveSourceMap(
-  fileName: string,
-  line: number,
-  col: number,
-): { fileName: string; line: number; col: number } {
-  if (!findSourceMap) return { fileName, line, col };
-  // pnpm uses symlinks; findSourceMap only matches the real path
-  const real = getRealPath(fileName);
-  const map = findSourceMap(real);
-  if (!map) return { fileName, line, col };
-  const entry = map.findEntry(line - 1, col - 1);
-  if (!entry) return { fileName, line, col };
-  return {
-    fileName: entry.originalSource,
-    line: entry.originalLine + 1,
-    col: entry.originalColumn + 1,
-  };
-}
-
 // V8 structured stack capture — avoids string formatting entirely
 const structuredPrepare = (
   _err: Error,
@@ -227,7 +147,7 @@ export function captureSourceLocation(
   skipReactives = true,
 ): SourceLocation | undefined {
   if (!isDebugEnabled()) return undefined;
-  loadFindSourceMap();
+  loadSourceMapSupport();
 
   const sites = captureCallSites();
 

package/src/debug/render.ts

@@ -17,6 +17,7 @@ import { getContext, untrack } from "../reactivity.js";
 import type { ComponentCreator } from "../runtime/component.js";
 import { flushJobsAsync } from "../scheduler.js";
 import { sanitizeRecord } from "./serialize.js";
+import { resolveComponentSource } from "./source-map.js";
 import {
   deleteDirectory,
   deleteOutputFile,
@@ -79,7 +80,10 @@ type TrackedNode = RenderedTextTree | PrintHook;
 let nodeIds = new WeakMap<TrackedNode, number>();
 let idToNode = new Map<number, TrackedNode>();
 let entryIds = new WeakMap<RenderedTextTree, number[]>();
-let nodeKinds = new WeakMap<TrackedNode, { kind: string; name?: string }>();
+let nodeKinds = new WeakMap<
+  TrackedNode,
+  { kind: string; name?: string; source?: RenderTreeNodeInfo["source"] }
+>();
 let fileNodes = new Map<number, { path: string; filetype: string }>();
 let directoryNodes = new Map<number, { path: string }>();
 let nodeProps = new Map<number, string | undefined>();
@@ -269,8 +273,12 @@ function recordNodeAdded(
   if (info.propsSerialized !== undefined) {
     nodeProps.set(id, info.propsSerialized);
   }
-  // Remember the kind so cached re-adds preserve it
-  nodeKinds.set(node, { kind: info.kind, name: info.name });
+  // Remember the kind and source so cached re-adds preserve them
+  nodeKinds.set(node, {
+    kind: info.kind,
+    name: info.name,
+    source: info.source,
+  });
   setEntryId(parent, index, id);
   insertRenderNode(
     id,
@@ -297,8 +305,11 @@ function recordSubtreeAdded(
   const existingId = nodeIds.get(subtree);
   const isCached = existingId !== undefined;
   const id = isCached ? existingId : getOrCreateNodeId(subtree);
-  // Remember the kind so cached re-adds preserve it
-  nodeKinds.set(subtree, { kind: info.kind, name: info.name });
+  // Merge source from previously-saved nodeKinds if the caller didn't provide one
+  const savedKind = nodeKinds.get(subtree);
+  const source = info.source ?? savedKind?.source;
+  // Remember the kind and source so cached re-adds preserve them
+  nodeKinds.set(subtree, { kind: info.kind, name: info.name, source });
   // Track in entryIds so clearRenderTreeChildren can find and remove it
   if (Array.isArray(parentNode)) {
     const list = getEntryList(parentNode);
@@ -310,9 +321,9 @@ function recordSubtreeAdded(
     info.kind,
     info.name,
     info.propsSerialized,
-    info.source?.fileName,
-    info.source?.lineNumber,
-    info.source?.columnNumber,
+    source?.fileName,
+    source?.lineNumber,
+    source?.columnNumber,
     null,
     undefined,
   );
@@ -366,7 +377,7 @@ function recordCachedSubtreeChildrenRecursively(node: RenderedTextTree) {
         );
       }
     } else if (Array.isArray(child)) {
-      // Nested RenderedTextTree - record and recurse, preserving original kind
+      // Nested RenderedTextTree - record and recurse, preserving original kind and source
       const id = getOrCreateNodeId(child);
       list.push(id);
       const savedKind = nodeKinds.get(child);
@@ -376,9 +387,9 @@ function recordCachedSubtreeChildrenRecursively(node: RenderedTextTree) {
         savedKind?.kind ?? "fragment",
         savedKind?.name,
         undefined,
-        undefined,
-        undefined,
-        undefined,
+        savedKind?.source?.fileName,
+        savedKind?.source?.lineNumber,
+        savedKind?.source?.columnNumber,
         null,
         undefined,
       );
@@ -544,6 +555,7 @@ export function beginComponent(
       }
     }
     const propsSerialized = serializeRenderTreeProps(propsSource);
+    const resolvedSource = resolveComponentSource(source);
     if (isExisting) {
       clearRenderTreeChildren(node);
     } else {
@@ -551,7 +563,7 @@ export function beginComponent(
         kind: "component",
         name: componentName,
         propsSerialized,
-        source,
+        source: resolvedSource,
       });
     }
 

package/src/debug/source-map.browser.ts

@@ -0,0 +1,30 @@
+/**
+ * Browser stub for source-map resolution.
+ *
+ * Source maps are not resolved in the browser — all functions pass through
+ * their inputs unchanged.
+ */
+
+import type { SourceLocation } from "../devtools/devtools-protocol.js";
+
+export function loadSourceMapSupport() {
+  // no-op in browser
+}
+
+export function getRealPath(fileName: string): string {
+  return fileName;
+}
+
+export function resolveSourceMap(
+  fileName: string,
+  line: number,
+  col: number,
+): { fileName: string; line: number; col: number } {
+  return { fileName, line, col };
+}
+
+export function resolveComponentSource(
+  source: SourceLocation | undefined,
+): SourceLocation | undefined {
+  return source;
+}

package/src/debug/source-map.ts

@@ -0,0 +1,135 @@
+/**
+ * Shared source-map resolution utilities.
+ *
+ * Used by both effect source capture (effects.ts) and component source
+ * resolution (render.ts) to convert file paths and resolve source maps.
+ */
+
+import type { SourceLocation } from "../devtools/devtools-protocol.js";
+
+// Lazily loaded findSourceMap from node:module
+let findSourceMap:
+  | ((path: string) =>
+      | {
+          findEntry: (
+            line: number,
+            col: number,
+          ) =>
+            | {
+                originalSource: string;
+                originalLine: number;
+                originalColumn: number;
+              }
+            | undefined;
+        }
+      | undefined)
+  | undefined;
+let loaded = false;
+let realpathSync: ((path: string) => string) | undefined;
+let fileURLToPath: ((url: string | URL) => string) | undefined;
+const realpathCache = new Map<string, string>();
+
+export function loadSourceMapSupport() {
+  if (loaded) return;
+  loaded = true;
+  try {
+    const mod = process.getBuiltinModule?.("node:module") as
+      | typeof import("node:module")
+      | undefined;
+    if (mod && typeof mod.findSourceMap === "function") {
+      findSourceMap = mod.findSourceMap as typeof findSourceMap;
+    }
+  } catch {
+    // not available
+  }
+  try {
+    const fs = process.getBuiltinModule?.("node:fs") as
+      | typeof import("node:fs")
+      | undefined;
+    if (fs) {
+      realpathSync = fs.realpathSync;
+    }
+  } catch {
+    // not available
+  }
+  try {
+    const url = process.getBuiltinModule?.("node:url") as
+      | typeof import("node:url")
+      | undefined;
+    if (url) {
+      fileURLToPath = url.fileURLToPath;
+    }
+  } catch {
+    // not available
+  }
+}
+
+export function getRealPath(fileName: string): string {
+  if (!realpathSync) return fileName;
+  let real = realpathCache.get(fileName);
+  if (real === undefined) {
+    try {
+      real = realpathSync(fileName);
+    } catch {
+      real = fileName;
+    }
+    realpathCache.set(fileName, real);
+  }
+  return real;
+}
+
+export function resolveSourceMap(
+  fileName: string,
+  line: number,
+  col: number,
+): { fileName: string; line: number; col: number } {
+  if (!findSourceMap) return { fileName, line, col };
+  // pnpm uses symlinks; findSourceMap only matches the real path
+  const real = getRealPath(fileName);
+  const map = findSourceMap(real);
+  if (!map) return { fileName, line, col };
+  const entry = map.findEntry(line - 1, col - 1);
+  if (!entry) return { fileName, line, col };
+  return {
+    fileName: entry.originalSource,
+    line: entry.originalLine + 1,
+    col: entry.originalColumn + 1,
+  };
+}
+
+function stripFileUrl(path: string): string {
+  if (!path.startsWith("file://")) return path;
+  if (fileURLToPath) return fileURLToPath(path);
+  return new URL(path).pathname;
+}
+
+/**
+ * Resolve a component source location. Handles:
+ * - `file://` URLs from import.meta.url (converts to file path)
+ * - Source map resolution (maps compiled .js to original .tsx)
+ * - Plain absolute paths (legacy format, returned as-is)
+ */
+export function resolveComponentSource(
+  source: SourceLocation | undefined,
+): SourceLocation | undefined {
+  if (!source?.fileName) return source;
+  loadSourceMapSupport();
+
+  const fileName = stripFileUrl(source.fileName);
+
+  if (source.lineNumber != null && source.columnNumber != null) {
+    // Resolve through source maps to get the original .tsx path
+    const resolved = resolveSourceMap(
+      fileName,
+      source.lineNumber,
+      source.columnNumber,
+    );
+    return {
+      fileName: stripFileUrl(resolved.fileName),
+      lineNumber: resolved.line,
+      columnNumber: resolved.col,
+    };
+  }
+
+  return { ...source, fileName };
+}

package/src/debug/trace.ts

@@ -3,6 +3,7 @@
  */
 import type { ServerToClientMessage } from "../devtools/devtools-protocol.js";
 import { isDevtoolsEnabled } from "../devtools/devtools-server.js";
+import { env, sourceMapsEnabled } from "../host/node-host.js";
 import { untrack } from "../reactivity.js";
 import { initTrace, isTraceEnabled } from "./trace-writer.js";
 
@@ -21,12 +22,12 @@ export function isDebugEnabled(): boolean {
 // Environment configuration
 // ─────────────────────────────────────────────────────────────────────────────
 
-const traceEnv = process.env.ALLOY_TRACE ?? "";
+const traceEnv = env("ALLOY_TRACE") ?? "";
 const tracePhases = new Set<string>(
   traceEnv === "" ? [] : traceEnv.split(",").map((t) => t.trim()),
 );
 
-const debuggerIdsEnv = process.env.ALLOY_BREAK_ON_DID ?? "";
+const debuggerIdsEnv = env("ALLOY_BREAK_ON_DID") ?? "";
 const debuggerIds = new Set<number>();
 debuggerIdsEnv.split(",").forEach((id) => {
   const num = parseInt(id, 10);
@@ -37,9 +38,9 @@ debuggerIdsEnv.split(",").forEach((id) => {
 
 /** Parse the ALLOY_BREAK_ON_DID environment variable into a set of IDs. */
 export function parseBreakOnIds(): Set<number> {
-  const env = process.env.ALLOY_BREAK_ON_DID ?? "";
+  const raw = env("ALLOY_BREAK_ON_DID") ?? "";
   const ids = new Set<number>();
-  env.split(",").forEach((id) => {
+  raw.split(",").forEach((id) => {
     const num = parseInt(id, 10);
     if (!isNaN(num)) {
       ids.add(num);
@@ -65,18 +66,34 @@ if (tracePhases.size > 0) {
 }
 
 // Initialize SQLite trace writer if ALLOY_DEBUG_TRACE is set
-const traceDbEnv = process.env.ALLOY_DEBUG_TRACE;
+const traceDbEnv = env("ALLOY_DEBUG_TRACE");
 if (traceDbEnv) {
   const traceDbPath =
     traceDbEnv === "1" || traceDbEnv === "true" ? "alloy-trace.db" : traceDbEnv;
   try {
     await initTrace(traceDbPath);
+    // eslint-disable-next-line no-console
+    console.log(`  Trace database: ${traceDbPath}`);
   } catch (e) {
     // eslint-disable-next-line no-console
     console.warn(`Failed to initialize trace database at ${traceDbPath}:`, e);
   }
 }
 
+if (import.meta.url.includes("/dist/dev/")) {
+  // eslint-disable-next-line no-console
+  console.log("Alloy debug build loaded.");
+  if (sourceMapsEnabled()) {
+    // eslint-disable-next-line no-console
+    console.log("  Source maps enabled.");
+  } else {
+    // eslint-disable-next-line no-console
+    console.log(
+      "  Source maps disabled. Run with --enable-source-maps for better stack traces.",
+    );
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Trace phases
 // ─────────────────────────────────────────────────────────────────────────────

package/src/host/node-host.browser.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser stub for Node.js host APIs.
+ *
+ * Replaces `node-host.ts` in browser builds so that no Node.js globals
+ * (`process`, etc.) are referenced.
+ */
+
+export function env(_key: string): string | undefined {
+  return undefined;
+}
+
+export function cwd(): string {
+  return "";
+}
+
+export function stdoutWrite(text: string): void {
+  // eslint-disable-next-line no-console
+  console.log(text);
+}
+
+export function sourceMapsEnabled(): boolean {
+  return false;
+}

package/src/host/node-host.ts

@@ -0,0 +1,22 @@
+/**
+ * Node.js host APIs.
+ *
+ * Provides access to Node.js-specific process APIs. In browser builds this
+ * module is replaced by `node-host.browser.ts` which returns safe defaults.
+ */
+
+export function env(key: string): string | undefined {
+  return process.env[key];
+}
+
+export function cwd(): string {
+  return process.cwd();
+}
+
+export function stdoutWrite(text: string): void {
+  process.stdout.write(text);
+}
+
+export function sourceMapsEnabled(): boolean {
+  return !!(process as any).sourceMapsEnabled;
+}

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";
 
@@ -125,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/write-output.ts

@@ -1,5 +1,6 @@
 import { dirname, relative, resolve } from "pathe";
 import { AlloyHost } from "./host/alloy-host.js";
+import { cwd } from "./host/node-host.js";
 import { OutputDirectory } from "./render.js";
 import { traverseOutput } from "./utils.js";
 /**
@@ -17,7 +18,7 @@ export async function writeOutput(
         return;
       }
       // eslint-disable-next-line no-console
-      console.log("create", relative(process.cwd(), path));
+      console.log("create", relative(cwd(), path));
       await AlloyHost.mkdir(path);
     },
     async visitFile(file) {
@@ -25,10 +26,10 @@ export async function writeOutput(
         const path = resolve(basePath, file.path);
         if (await AlloyHost.exists(path)) {
           // eslint-disable-next-line no-console
-          console.log("overwrite", relative(process.cwd(), path));
+          console.log("overwrite", relative(cwd(), path));
         } else {
           // eslint-disable-next-line no-console
-          console.log("create", relative(process.cwd(), path));
+          console.log("create", relative(cwd(), path));
         }
 
         await AlloyHost.write(path, file.contents);
@@ -38,10 +39,10 @@ export async function writeOutput(
         const target = resolve(basePath, file.path);
         if (await AlloyHost.exists(target)) {
           // eslint-disable-next-line no-console
-          console.log("copy over", relative(process.cwd(), target));
+          console.log("copy over", relative(cwd(), target));
         } else {
           // eslint-disable-next-line no-console
-          console.log("copy", relative(process.cwd(), target));
+          console.log("copy", relative(cwd(), target));
         }
         await AlloyHost.mkdir(dirname(target));
         await AlloyHost.write(target, AlloyHost.read(source).stream());