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

package/dist/src/scheduler.js

@@ -1,16 +1,47 @@
 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";
 const immediateQueue = new Set();
 const queue = new Set();
+function isJobActive(job) {
+  // ReactiveEffect uses bit 0 (flags & 1) as the ACTIVE flag.
+  // Skip effects that were stopped after being queued.
+  const flags = job.flags;
+  return flags === undefined || (flags & 1) !== 0;
+}
 const pendingPromises = new Set();
 let waitForSignalPromise = null;
 let resolveWaitForSignal = null;
 let jobSignalPromise = null;
 let resolveJobSignal = 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();
+
+/**
+ * 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, refId) {
+  lastTriggerRef.set(effectDebugId, refId);
+}
 export function scheduler(immediate = false) {
+  if (!immediate) return defaultScheduler;
   return function () {
-    queueJob(this, immediate);
+    queueJob(this, true);
   };
 }
+const defaultScheduler = function () {
+  queueJob(this, false);
+};
 export function queueJob(job, 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
@@ -25,6 +56,12 @@ export function queueJob(job, immediate = false) {
   } else {
     queue.add(job);
   }
+  if (isTraceEnabled()) {
+    const effectId = getEffectDebugId(job);
+    if (effectId !== undefined) {
+      insertSchedulerJob("queue", effectId, immediate, immediateQueue.size + queue.size);
+    }
+  }
   if (resolveJobSignal) {
     resolveJobSignal();
     resolveJobSignal = null;
@@ -44,15 +81,46 @@ export function trackPromise(promise) {
 }
 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);
+      if (effectId !== undefined) {
+        insertSchedulerJob("run", effectId, false, immediateQueue.size + queue.size);
+      }
+    }
+    if (!isJobActive(job)) {
+      if (isTraceEnabled()) {
+        const effectId = getEffectDebugId(job);
+        if (effectId !== undefined) {
+          insertEffectLifecycle(effectId, "skipped", undefined, undefined, undefined, undefined);
+        }
+      }
+      continue;
+    }
+    if (isTraceEnabled()) {
+      const effectId = getEffectDebugId(job);
+      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();
 }
 export function waitForSignal() {
@@ -79,29 +147,55 @@ 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);
+            if (effectId !== undefined) {
+              insertEffectLifecycle(effectId, "skipped", undefined, undefined, undefined, undefined);
+            }
+          }
+          continue;
+        }
+        if (isTraceEnabled()) {
+          const effectId = getEffectDebugId(job);
+          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 (!jobSignalPromise) {
-      jobSignalPromise = new Promise(resolve => {
-        resolveJobSignal = resolve;
-      });
-    }
+      // If there are no pending promises, we're done
+      if (pendingPromises.size === 0) {
+        break;
+      }
 
-    // Wait for either pending promises to complete or new jobs to arrive
-    await Promise.race([Promise.allSettled(Array.from(pendingPromises)), jobSignalPromise]);
+      // Commit before awaiting so writes are visible, then re-open after
+      if (isTraceEnabled()) commitTransaction();
+      if (!jobSignalPromise) {
+        jobSignalPromise = new Promise(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/dist/src/scheduler.js.map

@@ -1 +1 @@
-{"version":3,"names":["debug","immediateQueue","Set","queue","pendingPromises","waitForSignalPromise","resolveWaitForSignal","jobSignalPromise","resolveJobSignal","scheduler","immediate","queueJob","job","run","add","trackPromise","promise","finally","delete","flushJobs","takeJob","size","Error","render","flushJobsComplete","waitForSignal","Promise","resolve","signalSchedulerWait","isWaitingForSignal","flushJobsAsync","race","allSettled","Array","from","values","next","value"],"sources":["../../src/scheduler.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["debug","beginTransaction","commitTransaction","insertEffectLifecycle","insertSchedulerFlush","insertSchedulerJob","isTraceEnabled","getEffectDebugId","immediateQueue","Set","queue","isJobActive","job","flags","undefined","pendingPromises","waitForSignalPromise","resolveWaitForSignal","jobSignalPromise","resolveJobSignal","lastTriggerRef","Map","setLastTriggerRef","effectDebugId","refId","set","scheduler","immediate","defaultScheduler","queueJob","run","add","effectId","size","trackPromise","promise","finally","delete","flushJobs","jobCount","takeJob","triggerRefId","get","Error","render","flushJobsComplete","waitForSignal","Promise","resolve","signalSchedulerWait","isWaitingForSignal","flushJobsAsync","race","allSettled","Array","from","values","next","value"],"sources":["../../src/scheduler.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/src/symbols/output-scope.d.ts

@@ -40,6 +40,11 @@ export interface OutputScopeOptions {
  */
 export declare abstract class OutputScope {
     #private;
+    /**
+     * 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[]>;
     /**
      * The name of the scope.
@@ -69,7 +74,8 @@ export declare abstract class OutputScope {
     get parent(): OutputScope | undefined;
     set parent(scope: OutputScope | undefined);
     /**
-     * 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;
     /**
@@ -85,6 +91,32 @@ export declare abstract class OutputScope {
      */
     get binder(): Binder | undefined;
     [ReactiveFlags.SKIP]: boolean;
+    /**
+     * 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, options?: OutputScopeOptions);
     /**
      * Get all the declaration spaces in this scope.

package/dist/src/symbols/output-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-scope.d.ts","sourceRoot":"","sources":["../../../src/symbols/output-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EAMd,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIlD,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,WAAW;;IAC/B,MAAM,CAAC,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAe;IAGpE;;;;OAIG;IACH,IAAI,IAAI,IAKO,MAAM,CAFpB;IAED,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,EAIpB;IAGD;;;;OAIG;IACH,IAAI,EAAE,WAEL;IAID;;;;;OAKG;IACH,IAAI,QAAQ,4BAEX;IAID;;;;OAIG;IACH,IAAI,MAAM,IAKQ,WAAW,GAAG,SAAS,CAFxC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,EAaxC;IAID;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAK9C;;;;OAIG;IACH,IAAI,QAAQ,qBAEX;IAGD;;;;OAIG;IACH,IAAI,MAAM,uBAET;IAED,CAAC,aAAa,CAAC,IAAI,CAAC,UAAQ;gBAG1B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,OAAO,GAAE,kBAAuB;IAwClC;;;;OAIG;IACH,IAAI,MAAM,6BAET;IAGD;;;;;;;OAOG;IACH,IAAI,WAAW,6BAGd;IAED,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEvC;IAQD;;;;;;OAMG;IACH,IAAI,WAAW,YAMd;IACD;;;;;;;OAOG;IACH,IAAI,aAAa,YAEhB;IAED,CAAC,OAAO,CAAC,MAAM,CAAC;IAQhB,QAAQ;CAMT"}
+{"version":3,"file":"output-scope.d.ts","sourceRoot":"","sources":["../../../src/symbols/output-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EAKd,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIlD,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,WAAW;;IAC/B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAe;IAGpE;;;;OAIG;IACH,IAAI,IAAI,IAKO,MAAM,CAFpB;IAED,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,EAIpB;IAGD;;;;OAIG;IACH,IAAI,EAAE,WAEL;IAID;;;;;OAKG;IACH,IAAI,QAAQ,4BAEX;IAID;;;;OAIG;IACH,IAAI,MAAM,IAKQ,WAAW,GAAG,SAAS,CAFxC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,EAaxC;IAID;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAK9C;;;;OAIG;IACH,IAAI,QAAQ,qBAEX;IAGD;;;;OAIG;IACH,IAAI,MAAM,uBAET;IAED,CAAC,aAAa,CAAC,IAAI,CAAC,UAAQ;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;gBAED,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,OAAO,GAAE,kBAAuB;IAwClC;;;;OAIG;IACH,IAAI,MAAM,6BAET;IAGD;;;;;;;OAOG;IACH,IAAI,WAAW,6BAGd;IAED,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEvC;IAQD;;;;;;OAMG;IACH,IAAI,WAAW,YAMd;IACD;;;;;;;OAOG;IACH,IAAI,aAAa,YAEhB;IAED,CAAC,OAAO,CAAC,MAAM,CAAC;IAQhB,QAAQ;CAMT"}

package/dist/src/symbols/output-scope.js

@@ -1,7 +1,7 @@
-import { reactive, ReactiveFlags, shallowReactive, track, TrackOpTypes, trigger, TriggerOpTypes } from "@vue/reactivity";
+import { reactive, ReactiveFlags, track, TrackOpTypes, trigger, TriggerOpTypes } from "@vue/reactivity";
 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 } from "./output-space.js";
 let scopeCount = 0;
 /**
@@ -23,6 +23,11 @@ let scopeCount = 0;
  * within a reactive context.
  */
 export 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 declarationSpaces = [];
   #name;
   /**
@@ -85,7 +90,8 @@ export class OutputScope {
   #spaces;
 
   /**
-   * 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) {
     return this.#spaces[key];
@@ -109,6 +115,33 @@ export class OutputScope {
     return this.#binder;
   }
   [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, parentScope, options = {}) {
     this.#name = name;
     this.#id = scopeCount++;

package/dist/src/symbols/output-scope.js.map

@@ -1 +1 @@
-{"version":3,"names":["reactive","ReactiveFlags","shallowReactive","track","TrackOpTypes","trigger","TriggerOpTypes","useBinder","inspect","effect","untrack","OutputDeclarationSpace","scopeCount","OutputScope","declarationSpaces","name","GET","old","SET","id","metadata","parent","scope","children","delete","add","spaces","spaceFor","key","binder","SKIP","constructor","parentScope","options","Set","setOwnerSymbol","ownerSymbol","movedTo","undefined","debug","type","Object","fromEntries","map","spaceKey","notifyScopeCreated","values","debugInfo","#setOwnerSymbol","value","isTransient","isMemberScope","custom","toString"],"sources":["../../../src/symbols/output-scope.ts"],"sourcesContent":[null],"mappings":"AAAA,SACEA,QAAQ,EACRC,aAAa,EACbC,eAAe,EACfC,KAAK,EACLC,YAAY,EACZC,OAAO,EACPC,cAAc,QACT,iBAAiB;AAExB,SAASC,SAAS,QAAQ,sBAAsB;AAChD,SAASC,OAAO,QAAQ,eAAe;AACvC,SAASC,MAAM,EAAEC,OAAO,QAAQ,kBAAkB;AAClD,SAASC,sBAAsB,QAAqB,mBAAmB;AAGvE,IAAIC,UAAU,GAAG,CAAC;AAsBlB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAeC,WAAW,CAAC;EAChC,OAAgBC,iBAAiB,GAAuB,EAAE;EAE1D,CAACC,IAAI;EACL;AACF;AACA;AACA;AACA;EACE,IAAIA,IAAIA,CAAA,EAAG;IACTZ,KAAK,CAAC,IAAI,EAAEC,YAAY,CAACY,GAAG,EAAE,MAAM,CAAC;IACrC,OAAO,IAAI,CAAC,CAACD,IAAI;EACnB;EAEA,IAAIA,IAAIA,CAACA,IAAY,EAAE;IACrB,MAAME,GAAG,GAAG,IAAI,CAAC,CAACF,IAAI;IACtB,IAAI,CAAC,CAACA,IAAI,GAAGA,IAAI;IACjBV,OAAO,CAAC,IAAI,EAAEC,cAAc,CAACY,GAAG,EAAE,MAAM,EAAEH,IAAI,EAAEE,GAAG,CAAC;EACtD;EAEA,CAACE,EAAE;EACH;AACF;AACA;AACA;AACA;EACE,IAAIA,EAAEA,CAAA,EAAG;IACP,OAAO,IAAI,CAAC,CAACA,EAAE;EACjB;;EAEA;EACA,CAACC,QAAQ;EACT;AACF;AACA;AACA;AACA;AACA;EACE,IAAIA,QAAQA,CAAA,EAAG;IACb,OAAO,IAAI,CAAC,CAACA,QAAQ;EACvB;EAEA,CAACC,MAAM;;EAEP;AACF;AACA;AACA;AACA;EACE,IAAIA,MAAMA,CAAA,EAAG;IACXlB,KAAK,CAAC,IAAI,EAAEC,YAAY,CAACY,GAAG,EAAE,QAAQ,CAAC;IACvC,OAAO,IAAI,CAAC,CAACK,MAAM;EACrB;EAEA,IAAIA,MAAMA,CAACC,KAA8B,EAAE;IACzC,MAAML,GAAG,GAAG,IAAI,CAAC,CAACI,MAAM;IAExB,IAAIJ,GAAG,EAAE;MACPA,GAAG,CAACM,QAAQ,CAACC,MAAM,CAAC,IAAI,CAAC;IAC3B;IAEA,IAAIF,KAAK,EAAE;MACTA,KAAK,CAACC,QAAQ,CAACE,GAAG,CAAC,IAAI,CAAC;IAC1B;IAEApB,OAAO,CAAC,IAAI,EAAEC,cAAc,CAACY,GAAG,EAAE,QAAQ,EAAEI,KAAK,EAAEL,GAAG,CAAC;IACvD,IAAI,CAAC,CAACI,MAAM,GAAGC,KAAK;EACtB;EAEA,CAACI,MAAM;;EAEP;AACF;AACA;EACEC,QAAQA,CAACC,GAAW,EAA2B;IAC7C,OAAO,IAAI,CAAC,CAACF,MAAM,CAACE,GAAG,CAAC;EAC1B;EAEA,CAACL,QAAQ;EACT;AACF;AACA;AACA;AACA;EACE,IAAIA,QAAQA,CAAA,EAAG;IACb,OAAO,IAAI,CAAC,CAACA,QAAQ;EACvB;EAEA,CAACM,MAAM;EACP;AACF;AACA;AACA;AACA;EACE,IAAIA,MAAMA,CAAA,EAAG;IACX,OAAO,IAAI,CAAC,CAACA,MAAM;EACrB;EAEA,CAAC5B,aAAa,CAAC6B,IAAI,IAAI,IAAI;EAE3BC,WAAWA,CACThB,IAAY,EACZiB,WAAoC,EACpCC,OAA2B,GAAG,CAAC,CAAC,EAChC;IACA,IAAI,CAAC,CAAClB,IAAI,GAAGA,IAAI;IACjB,IAAI,CAAC,CAACI,EAAE,GAAGP,UAAU,EAAE;IACvB,IAAI,CAAC,CAACQ,QAAQ,GAAGpB,QAAQ,CAACiC,OAAO,CAACb,QAAQ,IAAI,CAAC,CAAC,CAAC;IACjD,IAAI,CAAC,CAACS,MAAM,GAAGI,OAAO,CAACJ,MAAM,IAAItB,SAAS,CAAC,CAAC;IAC5C,IAAI,CAAC,CAACgB,QAAQ,GAAGrB,eAAe,CAAC,IAAIgC,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,CAAC,CAACb,MAAM,GAAGW,WAAW;IAC1BvB,MAAM,CACJ,MAAM;MACJ,IAAI,CAAC,CAAC0B,cAAc,CAClBF,OAAO,CAACG,WAAW,EAAEC,OAAO,IAAIJ,OAAO,CAACG,WAC1C,CAAC;IACH,CAAC,EACDE,SAAS,EACT;MACEC,KAAK,EAAE;QACLxB,IAAI,EAAE,yBAAyB;QAC/ByB,IAAI,EAAE;MACR;IACF,CACF,CAAC;IAED,IAAI,IAAI,CAAC,CAACnB,MAAM,EAAE;MAChB,IAAI,CAAC,CAACA,MAAM,CAACE,QAAQ,CAACE,GAAG,CAAC,IAAI,CAAC;IACjC;IAEA,MAAMM,WAAW,GAAG,IAAI,CAACA,WAAiC;IAE1D,IAAI,CAAC,CAACL,MAAM,GAAGe,MAAM,CAACC,WAAW,CAC/BX,WAAW,CAACjB,iBAAiB,CAAC6B,GAAG,CAAEC,QAAQ,IAAK,CAC9CA,QAAQ,EACR,IAAIjC,sBAAsB,CAAC,IAAI,EAAEiC,QAAQ,EAAE,IAAI,CAAC,CAACf,MAAM,CAAC,CACzD,CACH,CAAC;;IAED;IACA,IAAI,CAAC,CAACA,MAAM,EAAEgB,kBAAkB,CAAC,IAAI,CAAC;EACxC;;EAEA;AACF;AACA;AACA;AACA;EACE,IAAInB,MAAMA,CAAA,EAAG;IACX,OAAOe,MAAM,CAACK,MAAM,CAAC,IAAI,CAAC,CAACpB,MAAM,CAAC;EACpC;EAEA,CAACU,WAAW;EACZ;AACF;AACA;AACA;AACA;AACA;AACA;AACA;EACE,IAAIA,WAAWA,CAAA,EAAG;IAChBjC,KAAK,CAAC,IAAI,EAAEC,YAAY,CAACY,GAAG,EAAE,aAAa,CAAC;IAC5C,OAAO,IAAI,CAAC,CAACoB,WAAW;EAC1B;EAEA,IAAIW,SAASA,CAAA,EAA4B;IACvC,OAAO,CAAC,CAAC;EACX;EAEA,CAACZ,cAAca,CAACC,KAA+B,EAAE;IAC/C,MAAMhC,GAAG,GAAG,IAAI,CAAC,CAACmB,WAAW;IAC7B,IAAI,CAAC,CAACA,WAAW,GAAGa,KAAK;IACzB5C,OAAO,CAAC,IAAI,EAAEC,cAAc,CAACY,GAAG,EAAE,aAAa,EAAE+B,KAAK,EAAEhC,GAAG,CAAC;EAC9D;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;EACE,IAAIiC,WAAWA,CAAA,EAAG;IAChB,IAAI,CAAC,IAAI,CAACd,WAAW,EAAE;MACrB,OAAO,KAAK;IACd;IAEA,OAAO,IAAI,CAACA,WAAW,CAACc,WAAW;EACrC;EACA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;EACE,IAAIC,aAAaA,CAAA,EAAG;IAClB,OAAO,CAAC,CAAC,IAAI,CAACf,WAAW;EAC3B;EAEA,CAAC5B,OAAO,CAAC4C,MAAM,IAAI;IACjB,MAAMhB,WAAW,GACf,IAAI,CAACA,WAAW,GAAG,QAAQ5B,OAAO,CAAC,IAAI,CAAC4B,WAAW,CAAC,EAAE,GAAG,EAAE;IAC7D,OAAO1B,OAAO,CACZ,MAAM,GAAG,IAAI,CAACqB,WAAW,CAAChB,IAAI,IAAI,IAAI,CAACA,IAAI,IAAI,IAAI,CAACI,EAAE,IAAIiB,WAAW,EACvE,CAAC;EACH;EAEAiB,QAAQA,CAAA,EAAG;IACT,OAAO3C,OAAO,CAAC,MAAM;MACnB,MAAM0B,WAAW,GAAG,IAAI,CAACA,WAAW,GAAG,QAAQ,IAAI,CAACA,WAAW,EAAE,GAAG,EAAE;MACtE,OAAO,GAAG,IAAI,CAACL,WAAW,CAAChB,IAAI,IAAI,IAAI,CAACA,IAAI,IAAI,IAAI,CAACI,EAAE,IAAIiB,WAAW,EAAE;IAC1E,CAAC,CAAC;EACJ;AACF","ignoreList":[]}
+{"version":3,"names":["reactive","ReactiveFlags","track","TrackOpTypes","trigger","TriggerOpTypes","useBinder","inspect","effect","shallowReactive","untrack","OutputDeclarationSpace","scopeCount","OutputScope","declarationSpaces","name","GET","old","SET","id","metadata","parent","scope","children","delete","add","spaces","spaceFor","key","binder","SKIP","constructor","parentScope","options","Set","setOwnerSymbol","ownerSymbol","movedTo","undefined","debug","type","Object","fromEntries","map","spaceKey","notifyScopeCreated","values","debugInfo","#setOwnerSymbol","value","isTransient","isMemberScope","custom","toString"],"sources":["../../../src/symbols/output-scope.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/src/symbols/output-space.d.ts

@@ -3,7 +3,15 @@ import { inspect } from "../inspect.js";
 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 declare class OutputDeclarationSpace extends SymbolTable {
     #private;
     constructor(scope: OutputScope, key: string, binder?: Binder);
@@ -13,6 +21,10 @@ export declare class OutputDeclarationSpace extends SymbolTable {
     get scope(): OutputScope;
     [inspect.custom](): string;
 }
+/**
+ * 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 declare class OutputMemberSpace extends SymbolTable {
     #private;
     constructor(symbol: OutputSymbol, key: string, binder?: Binder);

package/dist/src/symbols/output-space.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-space.d.ts","sourceRoot":"","sources":["../../../src/symbols/output-space.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG,sBAAsB,GAAG,iBAAiB,CAAC;AACrE,qBAAa,sBAAuB,SAAQ,WAAW;;gBACzC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAM5D;;OAEG;IACH,IAAI,KAAK,gBAER;IAED,CAAC,OAAO,CAAC,MAAM,CAAC;CAKjB;AAED,qBAAa,iBAAkB,SAAQ,WAAW;;gBACpC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAM9D;;OAEG;IACH,IAAI,MAAM,iBAET;IAED,CAAC,OAAO,CAAC,MAAM,CAAC;CAKjB"}
+{"version":3,"file":"output-space.d.ts","sourceRoot":"","sources":["../../../src/symbols/output-space.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,sBAAsB,GAAG,iBAAiB,CAAC;AAErE;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,WAAW;;gBACzC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAM5D;;OAEG;IACH,IAAI,KAAK,gBAER;IAED,CAAC,OAAO,CAAC,MAAM,CAAC;CAKjB;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;;gBACpC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAM9D;;OAEG;IACH,IAAI,MAAM,iBAET;IAED,CAAC,OAAO,CAAC,MAAM,CAAC;CAKjB"}

package/dist/src/symbols/output-space.js

@@ -1,6 +1,16 @@
 import { inspect } from "../inspect.js";
 import { untrack } from "../reactivity.js";
 import { SymbolTable } from "./symbol-table.js";
+
+/**
+ * A symbol table that belongs to either a scope (declaration space) or a symbol
+ * (member space).
+ */
+
+/**
+ * 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, key, binder) {
     super(key, binder);
@@ -17,6 +27,11 @@ export class OutputDeclarationSpace extends SymbolTable {
     return untrack(() => `OutputDeclarationSpace for scope ${inspect(this.#scope)}`);
   }
 }
+
+/**
+ * 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, key, binder) {
     super(key, binder);

package/dist/src/symbols/output-space.js.map

@@ -1 +1 @@
-{"version":3,"names":["inspect","untrack","SymbolTable","OutputDeclarationSpace","constructor","scope","key","binder","custom","OutputMemberSpace","symbol"],"sources":["../../../src/symbols/output-space.ts"],"sourcesContent":[null],"mappings":"AACA,SAASA,OAAO,QAAQ,eAAe;AACvC,SAASC,OAAO,QAAQ,kBAAkB;AAG1C,SAASC,WAAW,QAAQ,mBAAmB;AAG/C,OAAO,MAAMC,sBAAsB,SAASD,WAAW,CAAC;EACtDE,WAAWA,CAACC,KAAkB,EAAEC,GAAW,EAAEC,MAAe,EAAE;IAC5D,KAAK,CAACD,GAAG,EAAEC,MAAM,CAAC;IAClB,IAAI,CAAC,CAACF,KAAK,GAAGA,KAAK;EACrB;EAEA,CAACA,KAAK;EACN;AACF;AACA;EACE,IAAIA,KAAKA,CAAA,EAAG;IACV,OAAO,IAAI,CAAC,CAACA,KAAK;EACpB;EAEA,CAACL,OAAO,CAACQ,MAAM,IAAI;IACjB,OAAOP,OAAO,CACZ,MAAM,oCAAoCD,OAAO,CAAC,IAAI,CAAC,CAACK,KAAK,CAAC,EAChE,CAAC;EACH;AACF;AAEA,OAAO,MAAMI,iBAAiB,SAASP,WAAW,CAAC;EACjDE,WAAWA,CAACM,MAAoB,EAAEJ,GAAW,EAAEC,MAAe,EAAE;IAC9D,KAAK,CAACD,GAAG,EAAEC,MAAM,CAAC;IAClB,IAAI,CAAC,CAACG,MAAM,GAAGA,MAAM;EACvB;EAEA,CAACA,MAAM;EACP;AACF;AACA;EACE,IAAIA,MAAMA,CAAA,EAAG;IACX,OAAO,IAAI,CAAC,CAACA,MAAM;EACrB;EAEA,CAACV,OAAO,CAACQ,MAAM,IAAI;IACjB,OAAOP,OAAO,CACZ,MAAM,gCAAgCD,OAAO,CAAC,IAAI,CAAC,CAACU,MAAM,CAAC,EAC7D,CAAC;EACH;AACF","ignoreList":[]}
+{"version":3,"names":["inspect","untrack","SymbolTable","OutputDeclarationSpace","constructor","scope","key","binder","custom","OutputMemberSpace","symbol"],"sources":["../../../src/symbols/output-space.ts"],"sourcesContent":[null],"mappings":"AACA,SAASA,OAAO,QAAQ,eAAe;AACvC,SAASC,OAAO,QAAQ,kBAAkB;AAG1C,SAASC,WAAW,QAAQ,mBAAmB;;AAE/C;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA,OAAO,MAAMC,sBAAsB,SAASD,WAAW,CAAC;EACtDE,WAAWA,CAACC,KAAkB,EAAEC,GAAW,EAAEC,MAAe,EAAE;IAC5D,KAAK,CAACD,GAAG,EAAEC,MAAM,CAAC;IAClB,IAAI,CAAC,CAACF,KAAK,GAAGA,KAAK;EACrB;EAEA,CAACA,KAAK;EACN;AACF;AACA;EACE,IAAIA,KAAKA,CAAA,EAAG;IACV,OAAO,IAAI,CAAC,CAACA,KAAK;EACpB;EAEA,CAACL,OAAO,CAACQ,MAAM,IAAI;IACjB,OAAOP,OAAO,CACZ,MAAM,oCAAoCD,OAAO,CAAC,IAAI,CAAC,CAACK,KAAK,CAAC,EAChE,CAAC;EACH;AACF;;AAEA;AACA;AACA;AACA;AACA,OAAO,MAAMI,iBAAiB,SAASP,WAAW,CAAC;EACjDE,WAAWA,CAACM,MAAoB,EAAEJ,GAAW,EAAEC,MAAe,EAAE;IAC9D,KAAK,CAACD,GAAG,EAAEC,MAAM,CAAC;IAClB,IAAI,CAAC,CAACG,MAAM,GAAGA,MAAM;EACvB;EAEA,CAACA,MAAM;EACP;AACF;AACA;EACE,IAAIA,MAAMA,CAAA,EAAG;IACX,OAAO,IAAI,CAAC,CAACA,MAAM;EACrB;EAEA,CAACV,OAAO,CAACQ,MAAM,IAAI;IACjB,OAAOP,OAAO,CACZ,MAAM,gCAAgCD,OAAO,CAAC,IAAI,CAAC,CAACU,MAAM,CAAC,EAC7D,CAAC;EACH;AACF","ignoreList":[]}

package/dist/src/symbols/output-symbol.d.ts

@@ -10,6 +10,12 @@ export interface OutputSymbolOptions {
      * will be reported to this binder. This binder will be able to find this
      * symbol via its refkey and other means. Without a binder, this symbol will
      * be unbound, which means it cannot be referenced by refkey.
+     *
+     * @remarks
+     *
+     * When constructing an external library symbol, pass `{ binder }` here to
+     * ensure the symbol is registered with the binder. See {@link TO_SYMBOL} for
+     * the full implementation protocol.
      */
     binder?: Binder;
     /**
@@ -61,7 +67,15 @@ export interface OutputSymbolOptions {
      */
     ignoreNameConflict?: boolean;
     /**
-     * Provide a function which lazy-initializes members when an enumeration of members are needed.
+     * Provide a function which lazy-initializes members the first time
+     * `resolveMemberByName()` is called on this symbol. Called at most once.
+     *
+     * @remarks
+     *
+     * Only `resolveMemberByName()` triggers this callback — iterating
+     * `OutputMemberSpace` directly does not. The callback fires regardless of
+     * whether the symbol belongs to any scope, so it is safe to use on scopeless
+     * external library symbols.
      */
     lazyMemberInitializer?: () => void;
 }
@@ -71,12 +85,48 @@ export interface OutputSymbolOptions {
  *
  * @remarks
  *
- * This class is the base implementation of symbol. Most languages will have
- * subtypes that provide additional metadata. Symbols are reactive values, so
- * you can observe changes to their properties in a reactive context.
+ * This is an abstract base class. Language packages must subclass it and
+ * implement the abstract {@link OutputSymbol.copy | copy()} method, which
+ * creates a clone that tracks the original's name and flags.
+ *
+ * Subtypes typically add language-specific properties (e.g., accessibility,
+ * static/abstract flags). Symbols are reactive values, so you can observe
+ * changes to their properties in a reactive context.
+ *
+ * To construct a scopeless external library symbol — one that resolves via
+ * refkey but does not appear in any declaration space — pass `undefined` as
+ * the `spaces` constructor argument and supply `{ binder }` in `options`.
+ * See {@link OutputSymbolOptions} (`binder` option) and {@link TO_SYMBOL}.
+ *
+ * @example
+ *
+ * ```ts
+ * import { createSymbol, OutputSymbol, OutputSpace } from "@alloy-js/core";
+ *
+ * class MySymbol extends OutputSymbol {
+ *   copy() {
+ *     // getCopyOptions() already includes binder
+ *     const opts = this.getCopyOptions();
+ *     const sym = createSymbol(MySymbol, this.name, undefined, opts);
+ *     this.initializeCopy(sym);
+ *     return sym;
+ *   }
+ * }
+ *
+ * // name: string | Namekey; spaces: OutputSpace | OutputSpace[] | undefined; options: OutputSymbolOptions
+ * const sym = createSymbol(MySymbol, namekey, scope.symbols, { binder });
+ *
+ * // Construct a scopeless external library symbol (resolves via refkey only):
+ * const extSym = createSymbol(MySymbol, namekey, undefined, { binder });
+ * ```
  */
 export declare abstract class OutputSymbol {
     #private;
+    /**
+     * The member space keys for this symbol type. Subclasses override this to
+     * declare which member spaces are created on construction (e.g.,
+     * `["static", "instance"]`).
+     */
     static readonly memberSpaces: Readonly<string[]>;
     /**
      * Read only. The requested name of this symbol. The symbol's actual name may
@@ -86,12 +136,48 @@ export declare abstract class OutputSymbol {
      */
     get originalName(): string;
     /**
-     * The name of this symbol.
+     * The name of this symbol. Assigning to this property applies the active
+     * name policy (unless `ignoreNamePolicy` is true) before storing the value.
+     *
+     * The effective name is computed as `deconflictedName ?? userName`, so if a
+     * name-conflict resolver has assigned a {@link OutputSymbol.deconflictedName | deconflictedName}, that value
+     * is returned here; otherwise the value most recently assigned to `name` is
+     * returned.
      *
      * @reactive
      */
     get name(): string;
     set name(name: string);
+    /**
+     * The name assigned by a name-conflict resolver, or `undefined` when the
+     * symbol is not currently renamed by conflict resolution.
+     *
+     * Resolvers should assign to this slot (rather than `name`) to record that a
+     * rename exists only because of a conflict. On re-deconfliction (e.g. after
+     * a conflicting symbol is removed), resolvers clear this slot by assigning
+     * `undefined`; the effective {@link OutputSymbol.name | name} then falls back to the
+     * user-assigned name, which in turn falls back to the original name.
+     *
+     * Name policy is applied to values written here (unless `ignoreNamePolicy`
+     * is true), matching `name`'s behavior.
+     *
+     * @reactive
+     */
+    get deconflictedName(): string | undefined;
+    set deconflictedName(value: string | undefined);
+    /**
+     * The canonical requested name for this symbol: the result of applying the
+     * symbol's name policy to its {@link OutputSymbol.originalName | originalName}, or the original name
+     * itself when no policy applies. This is the name the symbol would carry if
+     * there were no conflicts, and is stable across the symbol's lifetime (it
+     * depends only on the immutable `originalName` and the name policy).
+     *
+     * Used by {@link SymbolTable} as the grouping key for name-conflict
+     * resolution, so that symbols whose original names normalize to the same
+     * policy-applied name (e.g. `foo_bar` and `fooBar` under camelCase) are
+     * recognized as conflicting.
+     */
+    get canonicalName(): string;
     /**
      * The unique id of this symbol.
      *
@@ -173,6 +259,13 @@ export declare abstract class OutputSymbol {
      * @readonly
      */
     get metadata(): Record<string, unknown>;
+    /**
+     * Copy this symbol into the given space. Calls {@link OutputSymbol.copy} and places
+     * the result in `space`, then returns the copy.
+     *
+     * @param space - The space to place the copy in.
+     * @returns The copy of this symbol, now belonging to `space`.
+     */
     copyToSpace(space: OutputSpace): OutputSymbol;
     /**
      * Whether this symbol is a member of another symbol.
@@ -235,6 +328,14 @@ export declare abstract class OutputSymbol {
      */
     resolveMemberByName(name: string): OutputSymbol | undefined;
     [ReactiveFlags.SKIP]: boolean;
+    /**
+     * @param name - The symbol name, or a {@link Namekey} carrying name and
+     * options (e.g., `ignoreNamePolicy`).
+     * @param spaces - The declaration or member space(s) this symbol belongs to.
+     * Pass `undefined` for scopeless external library symbols (see `binder` option).
+     * @param options - Additional symbol options (binder, refkeys, metadata,
+     * type, name policy, etc.).
+     */
     constructor(name: string | Namekey, spaces: OutputSpace[] | OutputSpace | undefined, options?: OutputSymbolOptions);
     delete(): void;
     /**
@@ -250,17 +351,19 @@ export declare abstract class OutputSymbol {
      */
     copyMembersTo(targetSymbol: OutputSymbol): void;
     /**
-     * Makes a copy of this symbol which will update the name and flags
-     * of the clone when the original symbol is updated.
+     * Create a clone of this symbol whose name and flags reactively track the
+     * original.
      *
      * @remarks
      *
-     * This is used to create a symbol that is a copy of this symbol, but
-     * with a different scope. Changes to the copy will not affect the
-     * original symbol, and changes to the original symbol's name and flags
-     * will overwrite the copy's name and flags.
+     * Called by `SymbolTable.copyTo` during scope/space transfers.
+     * Subclasses implement cloning logic and call `getCopyOptions` for
+     * base options and `initializeCopy` to wire up member copying and
+     * name tracking.
      *
-     * @param newScope - The scope to use for the copy.
+     * **Space registration contract:** The returned clone must not be registered
+     * in any space on exit. `copyToSpace()` calls this method and assigns the
+     * space afterward.
      */
     abstract copy(): OutputSymbol;
     protected getCopyOptions(): {
@@ -269,6 +372,19 @@ export declare abstract class OutputSymbol {
         metadata: Record<string, unknown>;
         transient: boolean;
     };
+    /**
+     * Wires up reactive member-space copying and name tracking from this symbol
+     * to its `copy`.
+     *
+     * @remarks
+     *
+     * Iterates each member space and calls `copyTo` on the corresponding space
+     * on `copy`. Then installs a reactive watcher so that any future change to
+     * `this.name` is immediately mirrored onto `copy.name`.
+     *
+     * **Must be called by every `copy()` override** before the override returns.
+     * Pair with `getCopyOptions` to supply the base constructor options.
+     */
     protected initializeCopy(copy: OutputSymbol): void;
     [inspect.custom](): string;
     toString(): string;