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

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

@@ -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","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":[]}
+{"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;

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

@@ -1 +1 @@
-{"version":3,"file":"output-symbol.d.ts","sourceRoot":"","sources":["../../../src/symbols/output-symbol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"output-symbol.d.ts","sourceRoot":"","sources":["../../../src/symbols/output-symbol.ts"],"names":[],"mappings":"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"}

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

@@ -14,11 +14,47 @@ let symbolCount = 0;
  *
  * @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 class OutputSymbol {
+  /**
+   * 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 memberSpaces = [];
   #originalName;
   /**
@@ -31,24 +67,95 @@ export class OutputSymbol {
     return this.#originalName;
   }
 
-  // this field is set by calling the name accessor.
-  #name;
+  // The user-assigned name (as set by constructor or direct `.name =`
+  // assignments). Always defined after construction.
+  #userName;
+
+  // The name assigned by a name-conflict resolver, if any. When present, this
+  // takes precedence over `#userName` in the computed `name` getter. Resolvers
+  // assign via the `deconflictedName` setter; clearing (setting to undefined)
+  // causes the symbol to fall back to its user-assigned name.
+  #deconflictedName;
+
   /**
-   * 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() {
     track(this, TrackOpTypes.GET, "name");
-    return this.#name;
+    return this.#deconflictedName ?? this.#userName;
   }
   set name(name) {
-    const old = this.#name;
-    if (old === name) {
+    const policyApplied = this.#namePolicy && !this.#ignoreNamePolicy ? this.#namePolicy(name) : name;
+    if (this.#userName === policyApplied) {
       return;
     }
-    this.#name = this.#namePolicy && !this.#ignoreNamePolicy ? this.#namePolicy(name) : name;
-    trigger(this, TriggerOpTypes.SET, "name", name, old);
+    const old = this.#deconflictedName ?? this.#userName;
+    this.#userName = policyApplied;
+    const next = this.#deconflictedName ?? this.#userName;
+    if (next !== old) {
+      trigger(this, TriggerOpTypes.SET, "name", next, old);
+    }
+  }
+
+  /**
+   * 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() {
+    track(this, TrackOpTypes.GET, "deconflictedName");
+    return this.#deconflictedName;
+  }
+  set deconflictedName(value) {
+    const policyApplied = value !== undefined && this.#namePolicy && !this.#ignoreNamePolicy ? this.#namePolicy(value) : value;
+    if (this.#deconflictedName === policyApplied) {
+      return;
+    }
+    const oldName = this.#deconflictedName ?? this.#userName;
+    const oldDeconflicted = this.#deconflictedName;
+    this.#deconflictedName = policyApplied;
+    trigger(this, TriggerOpTypes.SET, "deconflictedName", policyApplied, oldDeconflicted);
+    const nextName = this.#deconflictedName ?? this.#userName;
+    if (nextName !== oldName) {
+      trigger(this, TriggerOpTypes.SET, "name", nextName, oldName);
+    }
+  }
+
+  /**
+   * 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() {
+    if (this.#ignoreNamePolicy || !this.#namePolicy) {
+      return this.originalName;
+    }
+    return this.#namePolicy(this.originalName);
   }
   #id;
   /**
@@ -208,6 +315,14 @@ export class OutputSymbol {
   get metadata() {
     return this.#metadata;
   }
+
+  /**
+   * 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) {
     const copy = this.copy();
     copy.spaces = space;
@@ -360,6 +475,15 @@ export class OutputSymbol {
   // Tell \@vue/reactivity that this symbol should never be wrapped in a reactive
   // proxy.
   [ReactiveFlags.SKIP] = true;
+
+  /**
+   * @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, spaces, options = {}) {
     this.#binder = options.binder ?? useBinder();
     this.#namePolicy = options.namePolicy;
@@ -449,17 +573,19 @@ export class OutputSymbol {
   }
 
   /**
-   * 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.
    */
 
   getCopyOptions() {
@@ -470,6 +596,20 @@ export class OutputSymbol {
       transient: this.isTransient
     };
   }
+
+  /**
+   * 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.
+   */
   initializeCopy(copy) {
     for (const sourceSpace of this.memberSpaces) {
       const targetSpace = copy.memberSpaceFor(sourceSpace.key);