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

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.23.0-dev.0",
+  "version": "0.23.0-dev.8",
   "description": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alloy-framework/alloy.git"
+  },
   "main": "./dist/src/index.js",
   "exports": {
     ".": {
@@ -23,33 +27,43 @@
     },
     "./components": {
       "import": "./dist/src/components/index.js"
+    },
+    "./devtools": {
+      "types": "./dist/src/devtools-entry.d.ts",
+      "browser": "./dist/src/devtools-entry.browser.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/inspect.js": "./dist/src/inspect.browser.js",
-    "./src/inspect.ts": "./src/inspect.browser.ts"
+    "./src/inspect.ts": "./src/inspect.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"
   },
   "keywords": [],
   "author": "brian.terlson@microsoft.com",
   "license": "MIT",
   "dependencies": {
+    "@types/ws": "^8.18.1",
     "@vue/reactivity": "^3.5.13",
-    "picocolors": "^1.1.1",
     "cli-table3": "^0.6.5",
+    "devalue": "^5.6.2",
     "pathe": "^2.0.3",
-    "prettier": "^3.6.2"
+    "picocolors": "^1.1.1",
+    "prettier": "^3.6.2",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.0",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.0",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
+    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "concurrently": "^9.2.0",
     "typescript": "^5.8.3",
     "vite": "^7.0.6",
-    "vitest": "^3.2.4"
+    "vitest": "3.2.4"
   },
   "type": "module",
   "scripts": {

package/scripts/copy-devtools-ui.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { copyFile, mkdir } from "fs/promises";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const srcFile = join(__dirname, "../../devtools/dist/index.html");
+const destFile = join(__dirname, "../dist/devtools/index.html");
+
+async function copyDevtoolsUi() {
+  try {
+    await mkdir(dirname(destFile), { recursive: true });
+    await copyFile(srcFile, destFile);
+    // eslint-disable-next-line no-console
+    console.log("Copied devtools UI to core dist");
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error("Failed to copy devtools UI:", error);
+    process.exit(1);
+  }
+}
+
+void copyDevtoolsUi();

package/src/binder.ts

@@ -2,8 +2,11 @@ import { computed, Ref, ShallowRef, shallowRef } from "@vue/reactivity";
 import { useBinder } from "./context/binder.js";
 import { useMemberContext } from "./context/member-scope.js";
 import { useScope } from "./context/scope.js";
-import { effect } from "./reactivity.js";
+import { debug, TracePhase } from "./debug/index.js";
+import { emitDiagnostic, type DiagnosticHandle } from "./diagnostics.js";
+import { effect, onCleanup } from "./reactivity.js";
 import {
+  inspectRefkey,
   isMemberRefkey,
   MemberRefkey,
   refkey,
@@ -13,12 +16,7 @@ import {
 } from "./refkey.js";
 import { OutputScope } from "./symbols/output-scope.js";
 import { type OutputSymbol } from "./symbols/output-symbol.js";
-import {
-  formatRefkeys,
-  formatSymbolName,
-  trace,
-  TracePhase,
-} from "./tracer.js";
+import { formatRefkeys, formatSymbolName } from "./tracer.js";
 export type Metadata = object;
 
 /**
@@ -211,6 +209,24 @@ export interface BinderOptions {
   nameConflictResolver?: NameConflictResolver;
 }
 
+export function createScope<TScope extends OutputScope, Args extends unknown[]>(
+  ctor: new (...args: Args) => TScope,
+  ...args: Args
+): TScope {
+  const scope = new ctor(...args);
+  debug.symbols.registerScope(scope);
+  return scope;
+}
+
+export function createSymbol<
+  TSymbol extends OutputSymbol,
+  Args extends unknown[],
+>(ctor: new (...args: Args) => TSymbol, ...args: Args): TSymbol {
+  const symbol = new ctor(...args);
+  debug.symbols.registerSymbol(symbol);
+  return symbol;
+}
+
 export function createOutputBinder(options: BinderOptions = {}): Binder {
   const binder: Binder = {
     resolveDeclarationByKey,
@@ -247,6 +263,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   }
 
   function notifySymbolDeleted(symbol: OutputSymbol) {
+    debug.symbols.unregisterSymbol(symbol);
     if (!refkey) {
       return;
     }
@@ -458,25 +475,25 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     const resolvedSymbol = getSymbolForRefkey(refkey);
 
     return computed(() => {
-      trace(
+      debug.trace(
         TracePhase.resolve.pending,
         () => `Resolving ${formatRefkeys(refkey)}.`,
       );
       const symbol = resolvedSymbol.value as TSymbol;
       if (!symbol) {
-        trace(
+        debug.trace(
           TracePhase.resolve.failure,
           () => `No symbol for ${formatRefkeys(refkey)}.`,
         );
         return undefined;
       }
-      trace(
+      debug.trace(
         TracePhase.resolve.pending,
         () =>
           `${formatRefkeys(refkey)} resolved to ${formatSymbolName(symbol)}.`,
       );
       if (symbol.isTransient) {
-        trace(
+        debug.trace(
           TracePhase.resolve.failure,
           () => `Symbol ${formatSymbolName(symbol)} is transient.`,
         );
@@ -485,7 +502,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
 
       const chain = scopeChain(symbol.scope);
       if (chain.some((scope) => scope.isTransient)) {
-        trace(
+        debug.trace(
           TracePhase.resolve.failure,
           () => `Symbol ${formatSymbolName(symbol)} is in a transient scope.`,
         );
@@ -533,7 +550,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
         for (const descriptor of allDescriptors) {
           const member = descriptor.symbol as TSymbol;
           if (currentBase.isTyped && !currentBase.hasTypeSymbol) {
-            trace(
+            debug.trace(
               TracePhase.resolve.pending,
               () =>
                 `${formatRefkeys(refkey)} needs type information from a parent type.`,
@@ -550,7 +567,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
           currentBase = member;
         }
 
-        trace(
+        debug.trace(
           TracePhase.resolve.success,
           () =>
             `${formatRefkeys(refkey)} successfully resolved to ${formatSymbolName(symbol)}.`,
@@ -628,7 +645,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   function notifySymbolCreated(symbol: OutputSymbol): void {
     effect<Refkey[]>((oldRefkeys) => {
       if (symbol.refkeys) {
-        trace(
+        debug.trace(
           TracePhase.resolve.pending,
           () => `Notifying resolutions for ${formatRefkeys(symbol.refkeys)}.`,
         );
@@ -702,11 +719,49 @@ export function resolve<
     throw new Error("Can't resolve refkey without a binder");
   }
 
-  return binder.resolveDeclarationByKey(
+  const result = binder.resolveDeclarationByKey(
     scope as TScope,
     refkey,
     options,
   ) as any;
+
+  let diagnosticHandle: DiagnosticHandle | null = null;
+
+  effect(
+    () => {
+      if (result.value === undefined) {
+        // Emit diagnostic for this specific reference site
+        if (!diagnosticHandle) {
+          diagnosticHandle = emitDiagnostic({
+            severity: "warning",
+            message: `Unresolved refkey: ${inspectRefkey(refkey)}`,
+          });
+        }
+      } else {
+        // Dismiss diagnostic when resolved
+        if (diagnosticHandle) {
+          diagnosticHandle.dismiss();
+          diagnosticHandle = null;
+        }
+      }
+    },
+    undefined,
+    {
+      debug: {
+        name: `binder:resolve:${inspectRefkey(refkey)}`,
+        type: "binder",
+      },
+    },
+  );
+
+  onCleanup(() => {
+    if (diagnosticHandle) {
+      diagnosticHandle.dismiss();
+      diagnosticHandle = null;
+    }
+  });
+
+  return result;
 }
 
 /**

package/src/components/AppendFile.tsx

@@ -2,6 +2,7 @@ import { computed } from "@vue/reactivity";
 import { join } from "pathe";
 import { useContext } from "../context.js";
 import { SourceDirectoryContext } from "../context/source-directory.js";
+import { emitDiagnostic } from "../diagnostics.js";
 import { createFileResource } from "../resource.js";
 import { Children, isComponentCreator } from "../runtime/component.js";
 import { childrenArray } from "../utils.jsx";
@@ -98,9 +99,11 @@ export function AppendFile(props: AppendFileProps): Children {
       } else if ("content" in regionProps) {
         content = regionProps.content;
       } else {
-        throw new Error(
-          `AppendRegion "${regionProps.id}" must have either children or content`,
-        );
+        emitDiagnostic({
+          message: `AppendRegion "${regionProps.id}" must have either children or content`,
+          severity: "error",
+        });
+        // Still register the region to avoid duplicate "region not found" diagnostic
       }
 
       appendRegions[regionProps.id] = content;
@@ -115,9 +118,10 @@ export function AppendFile(props: AppendFileProps): Children {
   // Validate that all requested regions have corresponding AppendRegion children
   for (const regionId of regions) {
     if (!(regionId in appendRegions)) {
-      throw new Error(
-        `Region "${regionId}" specified but no corresponding AppendRegion child found`,
-      );
+      emitDiagnostic({
+        message: `Region "${regionId}" specified but no corresponding AppendRegion child found`,
+        severity: "error",
+      });
     }
   }
 
@@ -181,9 +185,10 @@ export function AppendFile(props: AppendFileProps): Children {
     for (const regionId of regions) {
       const info = sigilInfo[regionId];
       if (info && info.start !== null && info.end === null) {
-        throw new Error(
-          `Region "${regionId}" has start sigil but no corresponding end sigil`,
-        );
+        emitDiagnostic({
+          message: `Region "${regionId}" has start sigil but no corresponding end sigil`,
+          severity: "error",
+        });
       }
     }
 

package/src/components/Block.tsx

@@ -1,5 +1,5 @@
-import { computed } from "@vue/reactivity";
 import { createContentSlot } from "../content-slot.jsx";
+import { computed } from "../reactivity.js";
 import type { Children } from "../runtime/component.js";
 import { Indent } from "./Indent.jsx";
 

package/src/components/Declaration.tsx

@@ -1,3 +1,4 @@
+import { createSymbol } from "../binder.js";
 import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { DeclarationContext } from "../context/declaration.js";
@@ -83,7 +84,7 @@ export function Declaration(props: DeclarationProps) {
       );
     }
 
-    declaration = new BasicSymbol(props.name, scope.symbols, {
+    declaration = createSymbol(BasicSymbol, props.name, scope.symbols, {
       binder,
       refkeys: [props.refkey ?? []].flat(),
       metadata: props.metadata,

package/src/components/Scope.tsx

@@ -1,3 +1,4 @@
+import { createScope } from "../binder.js";
 import { ScopeContext, useScope } from "../context/scope.js";
 import type { Children } from "../runtime/component.js";
 import { BasicScope } from "../symbols/basic-scope.js";
@@ -58,7 +59,9 @@ export function Scope(props: ScopeProps) {
         "Scope component can only make scopes within a BasicScope",
       );
     }
-    scope = new BasicScope(props.name ?? "", parentScope, {
+    const binder = parentScope?.binder;
+    scope = createScope(BasicScope, props.name ?? "", parentScope, {
+      binder,
       metadata: props.metadata,
       ownerSymbol: props.ownerSymbol,
     });

package/src/components/TemplateFile.tsx

@@ -1,4 +1,5 @@
 import { computed } from "@vue/reactivity";
+import { emitDiagnostic } from "../diagnostics.js";
 import { createFileResource } from "../resource.js";
 import { Children, isComponentCreator } from "../runtime/component.js";
 import { childrenArray } from "../utils.jsx";
@@ -85,9 +86,12 @@ export function TemplateFile(props: TemplateFileProps): Children {
     } else if ("value" in variableProps) {
       value = variableProps.value;
     } else {
-      throw new Error(
-        `TemplateVariable "${variableProps.name}" must have either children or value`,
-      );
+      emitDiagnostic({
+        message: `TemplateVariable "${variableProps.name}" must have either children or value`,
+        severity: "error",
+      });
+      // Still register the variable to avoid duplicate diagnostics
+      value = "";
     }
 
     templateVariables[variableProps.name] = value;
@@ -100,9 +104,11 @@ export function TemplateFile(props: TemplateFileProps): Children {
     }
 
     if (templateResource.error) {
-      throw new Error(
-        `Failed to read template file "${props.src}": ${templateResource.error}`,
-      );
+      emitDiagnostic({
+        message: `Failed to read template file "${props.src}": ${templateResource.error}`,
+        severity: "error",
+      });
+      return "";
     }
 
     const templateContent = templateResource.data!;
@@ -131,9 +137,12 @@ export function TemplateFile(props: TemplateFileProps): Children {
       if (variableName in templateVariables) {
         result.push(templateVariables[variableName]);
       } else {
-        throw new Error(
-          `Template variable "${variableName}" not found in TemplateVariable children`,
-        );
+        emitDiagnostic({
+          message: `Template variable "${variableName}" not found in TemplateVariable children`,
+          severity: "error",
+        });
+        // Keep the placeholder in the output to make the error visible
+        result.push(`{{ ${variableName} }}`);
       }
 
       lastIndex = matchStart + fullMatch.length;

package/src/content-slot.tsx

@@ -1,4 +1,4 @@
-import { effect, Ref, shallowRef } from "@vue/reactivity";
+import { computed, Ref, shallowRef } from "@vue/reactivity";
 import { Show } from "./components/Show.jsx";
 import { getContext } from "./reactivity.js";
 import { Children, Component } from "./runtime/component.js";
@@ -54,14 +54,14 @@ export interface ContentSlot {
  * ```
  */
 export function createContentSlot(): ContentSlot {
-  const isEmpty = shallowRef<boolean>(false);
+  // Holds a reference to the rendering context's isEmpty ref once ContentSlot
+  // renders. Before that, reads fall through to a default of "not empty".
+  const isEmptySource = shallowRef<Ref<boolean>>();
+  const isEmpty = computed(() => isEmptySource.value?.value ?? false);
 
   function ContentSlot(props: { children: Children }) {
     const context = getContext()!;
-    effect(() => {
-      isEmpty.value = context.isEmpty!.value;
-    });
-
+    isEmptySource.value = context.isEmpty!;
     return props.children;
   }
   ContentSlot.ref = isEmpty;

package/src/context.ts

@@ -38,12 +38,22 @@ export function createContext<T = unknown>(
   const id = Symbol(name ?? "context");
   function Provider(props: ContextProviderProps<T>) {
     const context = getContext();
+    const contextName = name ?? "anonymous";
 
     const rendered = shallowRef();
-    effect(() => {
-      context!.context![id] = props.value;
-      rendered.value = () => props.children;
-    }, undefined);
+    effect(
+      () => {
+        context!.context![id] = props.value;
+        rendered.value = () => props.children;
+      },
+      undefined,
+      {
+        debug: {
+          name: `context:provider:${contextName}`,
+          type: "context",
+        },
+      },
+    );
 
     return rendered.value;
   }
@@ -54,6 +64,7 @@ export function createContext<T = unknown>(
     Provider,
     ProviderStc: stc(Provider),
   };
+  (Provider as any).contextName = name;
   contextsByKey.set(id, ctx);
   return ctx;
 }