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

package/src/library-symbol-reference.ts

@@ -1,10 +1,62 @@
 import { RefkeyableObject } from "./refkey.js";
 import { OutputSymbol } from "./symbols/output-symbol.js";
 
+/**
+ * Well-known symbol for the lazy-symbol-creation protocol used by external
+ * library descriptors. Objects implementing `[TO_SYMBOL]()` are recognized as
+ * {@link LibrarySymbolReference} values that can be passed anywhere a refkey
+ * is accepted.
+ *
+ * @remarks
+ *
+ * Implement `[TO_SYMBOL]()` on a descriptor object to register it as a
+ * referenceable library symbol. Inside the method:
+ *
+ * 1. Call {@link useBinder} to get the current binder context.
+ * 2. Look up (or create) the symbol for that binder in a
+ *    `WeakMap<object, OutputSymbol>` (use a sentinel object for the
+ *    no-binder case, since `WeakMap` keys must be objects).
+ * 3. On first creation, construct the symbol and register it into the
+ *    appropriate space for your library, passing `{ binder }`
+ *    (see {@link OutputSymbolOptions.binder}).
+ *
+ * The method is called by language package code each time the descriptor is
+ * used as a reference (e.g. inside `ref()`). It is NOT called by the binder
+ * itself.
+ *
+ * @example
+ *
+ * ```ts
+ * const defaultKey = {};
+ * const symbols = new WeakMap<object, MySymbol>();
+ * const descriptor: LibrarySymbolReference = {
+ *   [REFKEYABLE]() {
+ *     return descriptor[TO_SYMBOL]().refkeys[0];
+ *   },
+ *   [TO_SYMBOL]() {
+ *     const binder = useBinder();
+ *     const key = binder ?? defaultKey;
+ *     let sym = symbols.get(key);
+ *     if (!sym) {
+ *       sym = new MySymbol("SomeType", space, { binder });
+ *       symbols.set(key, sym);
+ *     }
+ *     return sym;
+ *   },
+ * };
+ * ```
+ */
 export const TO_SYMBOL: unique symbol = Symbol(
   "Alloy.RefkeyableObject.TO_SYMBOL",
 );
 
+/**
+ * An object that acts as a lazy reference to an external library symbol.
+ * Implements {@link REFKEYABLE} and `[TO_SYMBOL]()`.
+ *
+ * Use {@link isLibrarySymbolReference} to test whether an unknown value is a
+ * library symbol reference.
+ */
 export interface LibrarySymbolReference extends RefkeyableObject {
   [TO_SYMBOL](): OutputSymbol;
 }

package/src/name-policy.ts

@@ -1,20 +1,47 @@
+/**
+ * A function that transforms a name according to a naming policy for a
+ * specific element kind. Obtained from {@link NamePolicy.for}.
+ */
 export interface NamePolicyGetter {
   (originalName: string): string;
 }
 export interface NamePolicy<TElements extends string> {
   /**
-   * Apply the language policy to the provided name for the provided element
-   * type.
+   * Apply the language policy to the provided name for the provided element type.
+   * When `element` is `undefined`, returns `originalName` unchanged.
    */
   getName(originalName: string, element: TElements | undefined): string;
   /**
    * Get a function that takes a name and applies the naming policy to it.
+   * When `element` is `undefined`, returns an identity function.
    */
   for(element: TElements | undefined): NamePolicyGetter;
 }
 
+/**
+ * Creates a name policy that transforms symbol names based on element kind.
+ *
+ * @example
+ * ```ts
+ * const policy = createNamePolicy((name, element) => {
+ *   if (element === "value") return toCamelCase(name);
+ *   if (element === "type")  return toPascalCase(name);
+ *   return name;
+ * });
+ * <Output namePolicy={policy}>...</Output>
+ * ```
+ *
+ * @remarks
+ * `element` identifies the kind of declaration (e.g., `"value"`, `"type"`).
+ * The set of valid element strings is defined by the language package.
+ *
+ * When `element` is `undefined` (outside a declaration context), {@link NamePolicy.getName}
+ * and {@link NamePolicy.for} short-circuit and return the original name unchanged — the
+ * namer callback is **not** invoked. The namer therefore always receives a defined `T`.
+ * This means names outside a declaration context cannot be transformed by the policy.
+ */
 export function createNamePolicy<T extends string>(
-  namer: (name: string, elements: T) => string,
+  namer: (name: string, element: T) => string,
 ): NamePolicy<T> {
   const forCache = new Map<string, NamePolicyGetter>();
   const noopGetter = (name: string) => name;

package/src/reactivity.ts

@@ -14,14 +14,10 @@ import {
   toRef as vueToRef,
   toRefs as vueToRefs,
 } from "@vue/reactivity";
-import {
-  captureSourceLocation,
-  debug,
-  isDevtoolsEnabled,
-} from "./debug/index.js";
+import { captureSourceLocation, debug, isDebugEnabled } from "./debug/index.js";
 import { RenderedTextTree } from "./render.js";
 import { Children, ComponentCreator } from "./runtime/component.js";
-import { scheduler } from "./scheduler.js";
+import { scheduler, setLastTriggerRef } from "./scheduler.js";
 import type { OutputSymbol } from "./symbols/output-symbol.js";
 
 if ((globalThis as any).__ALLOY__) {
@@ -135,7 +131,9 @@ function resolveOwnerEffectContextId(context: Context): number | null {
  * ContentSlot, mapJoin). Most contexts don't need an isEmpty ref.
  */
 export function ensureIsEmpty(context: Context): Ref<boolean> {
-  context.isEmpty ??= ref(context.childrenWithContent === 0);
+  context.isEmpty ??= ref(context.childrenWithContent === 0, {
+    isInfrastructure: true,
+  });
   return context.isEmpty;
 }
 
@@ -202,8 +200,26 @@ export function findCurrentEffectId(): number | undefined {
   return undefined;
 }
 
+/**
+ * Returns a getter caching the result of `fn`. Re-evaluates when reactive
+ * dependencies change. See the [Reactivity docs](../../reactivity.md) for details.
+ *
+ * @param fn - Function to memoize.
+ * @param equal - Skip updates when value is unchanged.
+ * @param name - Debug label for traces.
+ * @returns A zero-argument getter returning the cached value.
+ *
+ * @example
+ * ```ts
+ * const fullName = memo(() => `${first.value} ${last.value}`);
+ * fullName(); // cached; re-evaluates when first or last changes
+ * ```
+ */
 export function memo<T>(fn: () => T, equal?: boolean, name?: string): () => T {
-  const o = shallowRef<T>();
+  const memoLabel = name ? `memo:${name}` : "memo";
+  const o = shallowRef<T>(undefined as T, {
+    label: memoLabel,
+  });
   effect(
     (prev) => {
       const res = fn();
@@ -239,13 +255,16 @@ export function effect<T>(
   };
 
   const debugInfo = options?.debug;
-  const effectId = debug.effect.register({
-    name: debugInfo?.name ?? fn.name,
-    type: debugInfo?.type,
-    createdAt: captureSourceLocation(),
-    contextId: context.id,
-    ownerContextId: resolveOwnerEffectContextId(context),
-  });
+  const effectId =
+    isDebugEnabled() ?
+      debug.effect.register({
+        name: debugInfo?.name ?? fn.name,
+        type: debugInfo?.type,
+        createdAt: captureSourceLocation(),
+        contextId: context.id,
+        ownerContextId: resolveOwnerEffectContextId(context),
+      })
+    : -1;
 
   if (effectId !== -1) {
     context.meta ??= {};
@@ -283,6 +302,23 @@ export function effect<T>(
           refId: id,
           targetKey,
         });
+      } else if (
+        typeof event.target === "object" &&
+        event.target !== null &&
+        targetKey !== undefined
+      ) {
+        const id = reactivePropertyRefId(event.target, targetKey);
+        debug.effect.ensureReactivePropertyRef({
+          id,
+          target: event.target,
+          key: targetKey,
+        });
+        debug.effect.track({
+          effectId,
+          target: event.target,
+          refId: id,
+          targetKey,
+        });
       } else {
         debug.effect.track({
           effectId,
@@ -292,8 +328,21 @@ export function effect<T>(
       }
     };
     effectOpts.onTrigger = (event: any) => {
+      if (!("target" in event)) {
+        // Vue Dep.notify() chain propagation — no actual reactive target.
+        // Skip recording: these are computed→subscriber notifications without
+        // a meaningful target reference.
+        return;
+      }
       const targetKey =
         typeof event.key === "symbol" ? event.key.toString() : event.key;
+      // findCurrentEffectId() works because onTrigger fires synchronously
+      // during the mutation, so globalContext still points to the producer.
+      const producerEffectId = findCurrentEffectId();
+      const causedBy =
+        producerEffectId !== undefined && producerEffectId !== effectId ?
+          producerEffectId
+        : undefined;
       if (isRef(event.target)) {
         const id = refId(event.target);
         debug.effect.ensureRef({ id, kind: "ref" });
@@ -302,14 +351,34 @@ export function effect<T>(
           target: event.target,
           refId: id,
           targetKey,
-          kind: "triggered-by",
+          causedBy,
+        });
+        setLastTriggerRef(effectId, id);
+      } else if (
+        typeof event.target === "object" &&
+        event.target !== null &&
+        targetKey !== undefined
+      ) {
+        const id = reactivePropertyRefId(event.target, targetKey);
+        debug.effect.ensureReactivePropertyRef({
+          id,
+          target: event.target,
+          key: targetKey,
+        });
+        debug.effect.trigger({
+          effectId,
+          target: event.target,
+          refId: id,
+          targetKey,
+          causedBy,
         });
+        setLastTriggerRef(effectId, id);
       } else {
         debug.effect.trigger({
           effectId,
           target: event.target,
           targetKey,
-          kind: "triggered-by",
+          causedBy,
         });
       }
     };
@@ -392,13 +461,15 @@ export function ref<T>(
   options?: { isInfrastructure?: boolean },
 ): Ref<T> {
   const result = vueRef(value) as Ref<T>;
-  debug.effect.registerRef({
-    id: refId(result, options?.isInfrastructure),
-    kind: "ref",
-    createdAt: captureSourceLocation(),
-    createdByEffectId: globalContext?.meta?.effectId,
-    isInfrastructure: options?.isInfrastructure,
-  });
+  if (isDebugEnabled()) {
+    debug.effect.registerRef({
+      id: refId(result),
+      kind: "ref",
+      createdAt: captureSourceLocation(),
+      createdByEffectId: globalContext?.meta?.effectId,
+      isInfrastructure: options?.isInfrastructure,
+    });
+  }
   return result;
 }
 
@@ -417,32 +488,37 @@ export function shallowReactive<T extends object>(
   target: T,
 ): ShallowReactive<T> {
   const result = vueShallowReactive(target);
-  if (isDevtoolsEnabled()) {
+  if (isDebugEnabled()) {
     // Store by raw target — Vue's onTrack/onTrigger events pass the raw object, not the proxy.
     reactiveCreationLocations.set(target, captureSourceLocation());
   }
   return result;
 }
 
-export function shallowRef<T>(value?: T): Ref<T> {
+export function shallowRef<T>(value?: T, options?: { label?: string }): Ref<T> {
   const result = vueShallowRef(value) as Ref<T>;
-  debug.effect.registerRef({
-    id: refId(result),
-    kind: "shallowRef",
-    createdAt: captureSourceLocation(),
-    createdByEffectId: globalContext?.meta?.effectId,
-  });
+  if (isDebugEnabled()) {
+    debug.effect.registerRef({
+      id: refId(result),
+      kind: "shallowRef",
+      label: options?.label,
+      createdAt: captureSourceLocation(),
+      createdByEffectId: globalContext?.meta?.effectId,
+    });
+  }
   return result;
 }
 
 export function computed<T>(getter: () => T): Ref<T> {
   const result = vueComputed(getter) as Ref<T>;
-  debug.effect.registerRef({
-    id: refId(result),
-    kind: "computed",
-    createdAt: captureSourceLocation(),
-    createdByEffectId: globalContext?.meta?.effectId,
-  });
+  if (isDebugEnabled()) {
+    debug.effect.registerRef({
+      id: refId(result),
+      kind: "computed",
+      createdAt: captureSourceLocation(),
+      createdByEffectId: globalContext?.meta?.effectId,
+    });
+  }
   return result;
 }
 
@@ -455,12 +531,14 @@ export function toRef<T extends object, K extends keyof T>(
     defaultValue === undefined ?
       (vueToRef(object, key) as Ref<T[K]>)
     : (vueToRef(object, key, defaultValue) as Ref<T[K]>);
-  debug.effect.registerRef({
-    id: refId(result),
-    kind: "toRef",
-    createdAt: captureSourceLocation(),
-    createdByEffectId: globalContext?.meta?.effectId,
-  });
+  if (isDebugEnabled()) {
+    debug.effect.registerRef({
+      id: refId(result),
+      kind: "toRef",
+      createdAt: captureSourceLocation(),
+      createdByEffectId: globalContext?.meta?.effectId,
+    });
+  }
   return result;
 }
 
@@ -468,31 +546,78 @@ export function toRefs<T extends object>(
   object: T,
 ): { [K in keyof T]: Ref<T[K]> } {
   const result = vueToRefs(object) as { [K in keyof T]: Ref<T[K]> };
-  for (const refValue of Object.values(result) as Ref<unknown>[]) {
-    debug.effect.registerRef({
-      id: refId(refValue),
-      kind: "toRef",
-      createdAt: captureSourceLocation(),
-      createdByEffectId: globalContext?.meta?.effectId,
-    });
+  if (isDebugEnabled()) {
+    for (const refValue of Object.values(result) as Ref<unknown>[]) {
+      debug.effect.registerRef({
+        id: refId(refValue),
+        kind: "toRef",
+        createdAt: captureSourceLocation(),
+        createdByEffectId: globalContext?.meta?.effectId,
+      });
+    }
   }
   return result;
 }
 
 const seenRefs = new WeakMap<Ref<unknown>, number>();
 let refIdCounter = 1;
-let infraRefIdCounter = -1;
 const effectIdMap = new WeakMap<object, number>();
 
-export function refId(ref: Ref<unknown>, isInfrastructure?: boolean): number {
+// Stable ID mapping for (reactive, key) pairs — each property acts as a virtual ref.
+const reactivePropertyIds = new WeakMap<object, Map<string | number, number>>();
+
+export function refId(ref: Ref<unknown>): number {
   let id = seenRefs.get(ref);
   if (id === undefined) {
-    id = isInfrastructure ? infraRefIdCounter-- : refIdCounter++;
+    id = refIdCounter++;
     seenRefs.set(ref, id);
   }
   return id;
 }
 
+/**
+ * Get a stable ref ID for a property of a reactive object.
+ * Each (target, key) pair gets a unique positive ID from the same counter as refs.
+ */
+export function reactivePropertyRefId(
+  target: object,
+  key: string | number,
+): number {
+  let keys = reactivePropertyIds.get(target);
+  if (!keys) {
+    keys = new Map();
+    reactivePropertyIds.set(target, keys);
+  }
+  let id = keys.get(key);
+  if (id === undefined) {
+    id = refIdCounter++;
+    keys.set(key, id);
+  }
+  return id;
+}
+
+/**
+ * Build a human-readable label for a reactive property like `symbolName.prop`.
+ */
+export function formatReactivePropertyLabel(
+  target: object,
+  key: string | number,
+): string {
+  let ownerLabel: string;
+  try {
+    const str = String(target);
+    // OutputSymbol toString() returns something like: TSOutputSymbol "MyInterface"[42]
+    // Trim to just the meaningful part
+    ownerLabel = str.length > 60 ? str.slice(0, 57) + "..." : str;
+  } catch {
+    ownerLabel = "reactive";
+  }
+  if (Array.isArray(target)) {
+    ownerLabel = "[]";
+  }
+  return `${ownerLabel}.${key}`;
+}
+
 /** Allocate a unique reactive target ID from the same counter space as ref IDs. */
 export function nextReactiveId(): number {
   return refIdCounter++;
@@ -500,7 +625,6 @@ export function nextReactiveId(): number {
 
 export function resetRefIdCounter(): void {
   refIdCounter = 1;
-  infraRefIdCounter = -1;
 }
 
 export function getEffectDebugId(effect: object): number | undefined {

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}`;