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

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog - @alloy-js/core
 
+## 0.23.1
+
+### Bug Fixes
+
+- [#400](https://github.com/alloy-framework/alloy/pull/400) Fix additional files missing browser shim
+- [#398](https://github.com/alloy-framework/alloy/pull/398) Reduce per-render overhead when devtools/debug are disabled. `isDevtoolsEnabled()` now caches the `ALLOY_DEBUG` env-var read at module load (use `refreshDebugState()` from tests that mutate the env var dynamically), and `effect()`, `ref()`, `shallowRef()`, `computed()`, `toRef()`, and `toRefs()` now gate their debug-hook bookkeeping behind `isDebugEnabled()` so the argument objects and source-location captures aren't built when debug is off.
+
+
+## 0.23.0
+
+### Bug Fixes
+
+- [#356](https://github.com/alloy-framework/alloy/pull/356) onCleanup callbacks are now untracked, which fixes cases where cleaning up some reactive context would trigger it to run again.
+- [#395](https://github.com/alloy-framework/alloy/pull/395) Fix O(N²) overhead in `DiagnosticsCollector`. `emit()` and `dismiss()` previously re-broadcast the entire diagnostic history on every call, which dominated render time on large workloads even when debug tracing was disabled (the default). Broadcasts are now skipped when tracing is off, and the trace writer sees per-diagnostic add/remove deltas instead of duplicated inserts.
+- [#376](https://github.com/alloy-framework/alloy/pull/376) Ensure node specific api have browser override
+- [#379](https://github.com/alloy-framework/alloy/pull/379) Fix SymbolSlot in FunctionBase being rendered twice when a parameter has both type and default, which caused the type symbol to be overwritten and member resolution to fail. Also add an error diagnostic when a SymbolSlot is rendered more than once.
+- [#361](https://github.com/alloy-framework/alloy/pull/361) Reduce allocation overhead: lazy Context fields (disposables, context, elementCache, isEmpty), `_lastEmpty` boolean for cheap empty-state propagation, `ensureIsEmpty()` gating, scheduler `isJobActive` check to skip stopped effects, `ReactiveUnionSet` per-item root-scope disposers, and hoisted `defaultScheduler` closure.
+- [#396](https://github.com/alloy-framework/alloy/pull/396) Fix TypeScript import handling:
+  
+  - Long `import { ... } from "..."` statements now break across multiple lines when they exceed `printWidth`, using the layout engine.
+  - Import statements generated via `ref()` into a TypeScript `<SourceFile>` are now reference-counted and torn down (symbol deleted, statement removed) when the last live reference is disposed — e.g. when a `<Show>` that referenced an external refkey toggles off. Previously the import would linger and subsequent re-renders could drift conflicting local names to `foo_3`, `foo_4`, etc.
+  - `createValueSymbol` / `createTypeSymbol` / `createTypeAndValueSymbol` now automatically delete their symbol when the component that created it unmounts. This fixes a long-standing leak where symbols declared via `<VarDeclaration>`, `<FunctionDeclaration>`, etc. survived `<Show>` unmounts.
+  
+  Improve name-conflict resolution:
+  
+  - `OutputSymbol` now exposes a `deconflictedName` slot separate from the user-assigned name. Name-conflict resolvers write the collision rename into this slot (the public `.name` getter returns `deconflictedName ?? userAssignedName ?? originalName`), and clear it once a collision is resolved so survivors revert to their plain name. This replaces a fragile regex-based "is this an auto-generated alias?" check that hard-coded the default resolver's `foo_N` rename scheme. Custom resolvers with any rename scheme (including Python's `foo_N_module` form) now revert correctly when one of the conflicting symbols is removed.
+  - `tsNameConflictResolver` and `pythonNameConflictResolver` have been migrated to write through `deconflictedName`.
+  - `SymbolTable` now groups conflicts by each symbol's _canonical_ name — the result of applying the symbol's name policy to its `originalName`. This means two symbols whose original names normalize to the same policy-applied name (e.g. `foo_bar` and `fooBar` under camelCase) are correctly detected as conflicting.
+
+### Features
+
+- [#362](https://github.com/alloy-framework/alloy/pull/362) Add `createAccessExpression` factory for building language-specific member/access expression components with shared call chain formatting, symbol resolution, and reactive optimization.
+- [#356](https://github.com/alloy-framework/alloy/pull/356) Add a new diagnostics reporting interface. Diagnostics will log that an error occurred but will not stop emission. Various things that used to cause errors will now log diagnostics instead, including missing regions in AppendFile and TemplateFile. Unresolved refkeys will also produce a diagnostic.
+- [#356](https://github.com/alloy-framework/alloy/pull/356) Add new `createScope` and `createSymbol` APIs which construct subclasses of `OutputScope` and `OutputSymbol`, respectively. These are necessary to register the created scopes and symbols with the new debugger interface.
+- [#356](https://github.com/alloy-framework/alloy/pull/356) Added a browser-based debugger which is started when the ALLOY_DEBUG environment variable is set. The debugger shows emitted files, scopes, symbols, render nodes, effects, diagnostics, and more.
+- [#356](https://github.com/alloy-framework/alloy/pull/356) Added options to `effect` to allow passing debug information that helps identify that effect.
+- [#356](https://github.com/alloy-framework/alloy/pull/356) Tracing will now capture both "trigger" and "triggered-by" events (previously we only traced triggered-by (and called it trigger).
+- [#350](https://github.com/alloy-framework/alloy/pull/350) Print richer stack traces when rendering fails.
+- [#368](https://github.com/alloy-framework/alloy/pull/368) Ship dev sources in package for debugging. Use node's --condition="development" flag to use this build.
+- [#366](https://github.com/alloy-framework/alloy/pull/366) Add SQLite-based trace storage for debug and devtools infrastructure, enabling structured recording of render trees, effects, reactive edges, scopes, symbols, and diagnostics during development builds.
+
+
 ## 0.22.0
 
 ### Bug Fixes

package/api-extractor.json

@@ -1,11 +1,4 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  "extends": "../../api-extractor.base.json",
-  "messages": {
-    "extractorMessageReporting": {
-      "ae-wrong-input-file-type": {
-        "logLevel": "none"
-      }
-    }
-  }
+  "extends": "../../api-extractor.base.json"
 }

package/api-extractor.testing.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor.base.json",
+  "mainEntryPointFilePath": "<projectFolder>/dist/testing/index.d.ts",
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "<projectFolder>/temp/api-testing.json"
+  },
+  "messages": {
+    "extractorMessageReporting": {
+      "ae-wrong-input-file-type": {
+        "logLevel": "none"
+      },
+      "ae-forgotten-export": {
+        "logLevel": "none"
+      }
+    }
+  }
+}

package/dist/dev/src/binder.js

@@ -0,0 +1,595 @@
+import { computed, shallowRef } from "@vue/reactivity";
+import { useBinder } from "./context/binder.js";
+import { useMemberContext } from "./context/member-scope.js";
+import { useScope } from "./context/scope.js";
+import { debug, TracePhase } from "./debug/index.js";
+import { emitDiagnostic } from "./diagnostics.js";
+import { effect, onCleanup } from "./reactivity.js";
+import { inspectRefkey, isMemberRefkey, refkey, toRefkey } from "./refkey.js";
+import { formatRefkeys, formatSymbolName } from "./tracer.js";
+
+/**
+ * The binder tracks all output scopes and symbols. Scopes are nested containers
+ * for symbols.
+ *
+ * @remarks
+ *
+ * Symbol information is reactive because in certain situations this data may
+ * change. For example, when a symbol becomes conflicted with another symbol,
+ * one of the symbol names may change. Ensure that you interact with binder
+ * values in a reactive context (i.e. within JSX/code template, or within
+ * memo/computed/etc).
+ *
+ */
+
+/**
+ * A successful resolution of a refkey.
+ *
+ * @example
+ *
+ * Let's say we have the following scopes and symbols:
+ *
+ * ```
+ * scope: global scope
+ * ├── scope: namespace scope 1
+ * │   └── symbol: foo
+ * │       └── static members
+ * │           └── symbol: bar
+ * └── scope: namespace scope 2
+ *    └── (resolve bar from here)
+ * ```
+ *
+ * When we resolve the refkey for `bar` from within `namespace scope 2`, we will get the following
+ * resolution result:
+ *
+ * * **targetDeclaration**: symbol bar, the symbol we resolved.
+ * * **commonScope**: global scope, because this is the most specific scope that contains both the declaration and the reference.
+ * * **pathUp**: [namespace scope 2], because this is the scope between the reference and the common scope.
+ * * **pathDown**: [namespace scope 1], because this is the scope between the common scope and the declaration
+ * * **memberPath**: [bar]
+ * * **lexicalDeclaration**: foo
+ * For deeper chains (e.g., foo.bar.baz where bar and baz are member symbols, foo is not): memberPath = [bar, baz], lexicalDeclaration = foo.
+ */
+
+/**
+ * Describes a member in a member access chain, tracking both the symbol
+ * and whether this specific member was accessed via a memberRefkey.
+ */
+
+/**
+ * A callable interface invoked by the binder when two or more symbols in the
+ * same scope share a name. The resolver mutates symbol names to eliminate
+ * conflicts (e.g., appending `_2`, `_3`).
+ *
+ * @remarks
+ * The resolver is called with the shared `name` and all symbols in the scope
+ * that have that original name. Rename a symbol by assigning to `symbol.name`.
+ * Symbols with `ignoreNameConflict: true` are excluded. The default resolver
+ * keeps the first symbol unchanged and renames subsequent ones
+ * `originalName + "_2"`, `originalName + "_3"`, etc.
+ *
+ * Assigned names pass through the active name policy before being stored;
+ * design suffixes to produce the correct final name after policy
+ * transformation, or set `ignoreNamePolicy` on the symbol after resolution.
+ *
+ * Conflict detection is keyed on `originalName`
+ * (see {@link OutputSymbol.originalName}). Symbols that differ in original
+ * name but normalize to the same policy-applied name are never detected as
+ * conflicting.
+ *
+ * @example
+ * ```ts
+ * const resolver: NameConflictResolver = (name, symbols) => {
+ *   for (let i = 1; i < symbols.length; i++) {
+ *     symbols[i].name = symbols[i].originalName + "_" + (i + 1);
+ *   }
+ * };
+ * ```
+ */
+
+/**
+ * The context for a member resolution. This is used to properly resolve a
+ * member in the MemberResolver.
+ */
+
+/**
+ * A callback that performs access-control filtering during member resolution.
+ *
+ * @remarks
+ *
+ * When provided to {@link ResolveDeclarationByKeyOptions}, it entirely replaces
+ * the default checks (ownership assertion and `isMemberSymbol` assertion).
+ *
+ * **Contract:**
+ * - **Return `void`** to accept the member.
+ * - **Throw an error** to reject the member — the error propagates to the caller,
+ *   matching the behavior of the default checks.
+ *
+ * @example
+ * ```ts
+ * const resolver: MemberResolver<MyScope, MySymbol> = (owner, member, ctx) => {
+ *   if (member.isPrivate && !ctx.isMemberAccess) {
+ *     throw new Error(`${member.name} is not accessible here`);
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link MemberResolutionContext} for available context properties.
+ */
+
+/**
+ * Construct a scope instance and register it with devtools. Prefer this over
+ * calling `new` directly so that debugging tools can track the scope.
+ *
+ * @remarks
+ *
+ * Inside a component, obtain the current scope with `useScope()` and pass it
+ * as the `parentScope` constructor argument so the new scope is wired into
+ * the scope tree.
+ *
+ * @example
+ * ```tsx
+ * function MyScope(props) {
+ *   const parentScope = useScope();
+ *   const scope = createScope(MyScope, "scope-name", parentScope);
+ *   return <Scope value={scope}>{props.children}</Scope>;
+ * }
+ * ```
+ *
+ * @param ctor - The scope subclass constructor.
+ * @param args - Positional arguments forwarded directly to the scope
+ * constructor; see {@link OutputScope} for the base-class constructor
+ * signature.
+ */
+export function createScope(ctor, ...args) {
+  const scope = new ctor(...args);
+  debug.symbols.registerScope(scope);
+  return scope;
+}
+
+/**
+ * Construct a symbol instance and register it with devtools. Prefer this over
+ * calling `new` directly so that debugging tools can track the symbol.
+ *
+ * @remarks
+ *
+ * Binder registration (via `useBinder()` + `notifySymbolCreated()`) happens
+ * inside the `OutputSymbol` constructor regardless of whether you use
+ * `createSymbol` or `new`. This helper only adds devtools registration.
+ *
+ * @param ctor - The symbol subclass constructor.
+ * @param args - Arguments forwarded to the constructor.
+ */
+export function createSymbol(ctor, ...args) {
+  const symbol = new ctor(...args);
+  debug.symbols.registerSymbol(symbol);
+  return symbol;
+}
+export function createOutputBinder(options = {}) {
+  const binder = {
+    resolveDeclarationByKey,
+    getSymbolForRefkey,
+    notifyScopeCreated,
+    notifySymbolCreated,
+    notifySymbolDeleted,
+    nameConflictResolver: options.nameConflictResolver
+  };
+  const knownDeclarations = new Map();
+  const waitingDeclarations = new Map();
+  const waitingSymbolNames = new Map();
+  const waitingScopeNames = new Map();
+  return binder;
+  function notifyScopeCreated(scope) {
+    if (!scope.parent || !waitingScopeNames.has(scope.parent)) {
+      return;
+    }
+    const waiting = waitingScopeNames.get(scope.parent);
+    if (waiting?.has(scope.name)) {
+      const ref = waiting.get(scope.name);
+      ref.value = scope;
+    }
+  }
+  function notifySymbolDeleted(symbol) {
+    debug.symbols.unregisterSymbol(symbol);
+    if (!refkey) {
+      return;
+    }
+    for (const refkey of symbol.refkeys) {
+      const resolution = waitingDeclarations.get(refkey);
+      if (!resolution) return;
+      resolution.value = undefined;
+    }
+  }
+  function buildResult(currentScope, targetDeclarationBase) {
+    const {
+      memberPath: targetMemberPath,
+      scopeChain: targetChain
+    } = scopeAndMemberChain(targetDeclarationBase);
+    let targetLexicalDeclaration = targetMemberPath && targetMemberPath.length > 0 ? targetMemberPath[0].ownerSymbol : targetDeclarationBase;
+    // when we are resolving from a scope which is a member scope and might have
+    // member scope parents, and any symbols in the member path are members of
+    // the member scope's owner symbol (i.e., those symbols are in scope where
+    // the reference is made), we replace the target member path with an entry
+    // on the scope chain.
+
+    // So, first we find all the owner symbols for any member scopes in scope
+    // for the reference.
+    const referenceChain = scopeChain(currentScope);
+    const inScopeSymbols = new Map();
+    for (const scope of referenceChain) {
+      if (scope.isMemberScope) {
+        inScopeSymbols.set(scope.ownerSymbol, scope);
+      }
+    }
+
+    // then if the lexical declaration symbol's members are in scope, remove the
+    // symbol from the member path and add its corresponding member scope to the
+    // target chain.
+    while (targetMemberPath.length > 0 && inScopeSymbols.has(targetLexicalDeclaration)) {
+      targetChain.push(inScopeSymbols.get(targetLexicalDeclaration));
+      targetLexicalDeclaration = targetMemberPath.shift();
+    }
+
+    // Now we replace any scopes in the target chain with corresponding scopes
+    // from the reference chain.
+    for (const [index, scope] of targetChain.entries()) {
+      if (inScopeSymbols.has(scope.ownerSymbol)) {
+        targetChain[index] = inScopeSymbols.get(scope.ownerSymbol);
+      }
+    }
+
+    // Next we look for member scopes in the target chain that correspond to
+    // member scopes in the reference chain. We splice the reference chain into
+    // the target chain at that point. This ensures that we establish the proper
+    // common scope and path up/down even if the reference chain has additional
+    // scopes above it (e.g. a scope for the current source file).
+    const commonMemberContainer = targetChain.findIndex(scope => scope.isMemberScope && inScopeSymbols.has(scope.ownerSymbol));
+    if (commonMemberContainer > -1) {
+      const sourceLocation = referenceChain.findIndex(scope => scope.isMemberScope && scope.ownerSymbol === targetChain[commonMemberContainer].ownerSymbol);
+
+      // source location is guaranteed to exist at this point.
+      targetChain.splice(0, commonMemberContainer + 1, ...referenceChain.slice(0, sourceLocation + 1));
+    }
+
+    // Now that we have the target chain and scopes, we can determine the common
+    // scopes and paths.
+    let diffStart = 0;
+    while (targetChain[diffStart] && referenceChain[diffStart] && targetChain[diffStart] === referenceChain[diffStart]) {
+      diffStart++;
+    }
+    const pathUp = referenceChain.slice(diffStart);
+    const pathDown = targetChain.slice(diffStart);
+    const commonScope = targetChain[diffStart - 1] ?? undefined;
+    return {
+      pathUp,
+      pathDown,
+      memberPath: targetMemberPath,
+      commonScope,
+      symbol: targetDeclarationBase,
+      lexicalDeclaration: targetLexicalDeclaration,
+      fullSymbolPath: targetChain,
+      fullReferencePath: referenceChain
+    };
+  }
+
+  /**
+   * Walk from the provided symbol up to the non-member symbol. This constitutes
+   * the member path. Then, walk from the first non-member symbol's scope up to
+   * the global scope. This constitutes the scope chain.
+   */
+  function scopeAndMemberChain(symbol) {
+    const result = {
+      memberPath: [],
+      scopeChain: []
+    };
+    let currentSymbol = symbol;
+    if (currentSymbol.isMemberSymbol) {
+      result.memberPath = [];
+      while (currentSymbol.isMemberSymbol) {
+        result.memberPath.unshift(currentSymbol);
+        currentSymbol = currentSymbol.ownerSymbol;
+      }
+    }
+    const startScope = currentSymbol.scope;
+    result.scopeChain = scopeChain(startScope);
+    return result;
+  }
+  function scopeChain(scope) {
+    const chain = [];
+    while (scope) {
+      chain.unshift(scope);
+      scope = scope.parent;
+    }
+    return chain;
+  }
+  function getSymbolForRefkey(refkeyable) {
+    const refkey = toRefkey(refkeyable);
+    if (waitingDeclarations.has(refkey)) {
+      return waitingDeclarations.get(refkey);
+    }
+    let symbolRef;
+    if (isMemberRefkey(refkey)) {
+      const baseSymbolRef = getSymbolForRefkey(refkey.base);
+      const memberSymbolRef = getMemberSymbolFromMemberRefkey(refkey);
+      symbolRef = computed(() => {
+        // even though we don't necessarily need the base symbol to be available
+        // yet (the member symbol might already be declared on a type), we wait
+        // to resolve the member refkey until the base symbol is available.
+        const baseSymbol = baseSymbolRef.value;
+        const memberSymbol = memberSymbolRef.value;
+        if (!baseSymbol || !memberSymbol) {
+          return undefined;
+        }
+        return memberSymbol;
+      });
+    } else {
+      symbolRef = shallowRef();
+    }
+    waitingDeclarations.set(refkey, symbolRef);
+    if (knownDeclarations.has(refkey)) {
+      symbolRef.value = knownDeclarations.get(refkey);
+    }
+    return symbolRef;
+  }
+
+  /**
+   * There are two ways to reference a member symbol - directly via its refkey,
+   * and via a member refkey. In the former case, we just find the member
+   * symbol, and then compute its path directly from there. In hte latter case,
+   * we need to find the base of the member expression, and then add the members
+   * from the (possibly nested) member refkey to result.
+   */
+  function resolveDeclarationByKey(currentScope, refkey, options = {}) {
+    const resolvedSymbol = getSymbolForRefkey(refkey);
+    return computed(() => {
+      debug.trace(TracePhase.resolve.pending, () => `Resolving ${formatRefkeys(refkey)}.`);
+      const symbol = resolvedSymbol.value;
+      if (!symbol) {
+        debug.trace(TracePhase.resolve.failure, () => `No symbol for ${formatRefkeys(refkey)}.`);
+        return undefined;
+      }
+      debug.trace(TracePhase.resolve.pending, () => `${formatRefkeys(refkey)} resolved to ${formatSymbolName(symbol)}.`);
+      if (symbol.isTransient) {
+        debug.trace(TracePhase.resolve.failure, () => `Symbol ${formatSymbolName(symbol)} is transient.`);
+        return undefined;
+      }
+      const chain = scopeChain(symbol.scope);
+      if (chain.some(scope => scope.isTransient)) {
+        debug.trace(TracePhase.resolve.failure, () => `Symbol ${formatSymbolName(symbol)} is in a transient scope.`);
+        return undefined;
+      }
+      let result;
+      let memberDescriptorsFromRefkey;
+      if (isMemberRefkey(refkey)) {
+        memberDescriptorsFromRefkey = getMemberPathFromRefkey(refkey);
+        result = buildResult(currentScope, memberDescriptorsFromRefkey[0].symbol);
+      } else {
+        memberDescriptorsFromRefkey = [];
+        result = buildResult(currentScope, symbol);
+      }
+
+      // When we have member descriptors, this first entry is already part of the result due to passing it
+      // to buildResult above, so we don't need it here.
+      const newMemberPathDescriptors = memberDescriptorsFromRefkey.slice(1);
+      const allDescriptors = [...result.memberPath.map(s => ({
+        symbol: s,
+        isMemberAccess: false
+      })), ...newMemberPathDescriptors];
+
+      // update the member path and resolved symbol from our member descriptors
+      // (if we have them)
+      if (memberDescriptorsFromRefkey.length > 0) {
+        for (const descriptor of newMemberPathDescriptors) {
+          result.memberPath.push(descriptor.symbol);
+        }
+        result.symbol = memberDescriptorsFromRefkey.at(-1).symbol;
+      }
+
+      // a subcomputed here ensures we don't lose the progress above When
+      // we fail to resolve because a type isn't available yet.
+      return computed(() => {
+        // resolve each member in the member path
+        let currentBase = result.lexicalDeclaration;
+        for (const descriptor of allDescriptors) {
+          const member = descriptor.symbol;
+          if (currentBase.isTyped && !currentBase.hasTypeSymbol) {
+            debug.trace(TracePhase.resolve.pending, () => `${formatRefkeys(refkey)} needs type information from a parent type.`);
+            // waiting for type
+            return undefined;
+          }
+          resolveMember(currentBase, member, options.memberResolver, {
+            referencePath: result.fullReferencePath,
+            isMemberAccess: descriptor.isMemberAccess
+          });
+          currentBase = member;
+        }
+        debug.trace(TracePhase.resolve.success, () => `${formatRefkeys(refkey)} successfully resolved to ${formatSymbolName(symbol)}.`);
+        return result;
+      }).value;
+    });
+  }
+
+  /**
+   * Extracts member descriptors from a refkey, tracking which members
+   * were accessed via memberRefkey for proper member resolution context.
+   */
+  function getMemberPathFromRefkey(refkey) {
+    if (isMemberRefkey(refkey)) {
+      return [...getMemberPathFromRefkey(refkey.base), {
+        symbol: getMemberSymbolFromMemberRefkey(refkey).value,
+        isMemberAccess: true
+      }];
+    }
+    return [{
+      symbol: getSymbolForRefkey(refkey).value,
+      isMemberAccess: false
+    }];
+  }
+  function getMemberSymbolFromMemberRefkey(refkey) {
+    if (typeof refkey.member === "string") {
+      return computed(() => {
+        const baseSymbol = getSymbolForRefkey(refkey.base).value;
+        if (!baseSymbol) {
+          return undefined;
+        }
+        return baseSymbol.resolveMemberByName(refkey.member);
+      });
+    } else {
+      return getSymbolForRefkey(refkey.member);
+    }
+  }
+  function resolveMember(base, member, memberResolver, context) {
+    if (memberResolver) {
+      memberResolver(base, member, context);
+    } else {
+      // default member resolution
+      if (!member.isMemberSymbol) {
+        throw new Error(`${formatSymbolName(member)} is not a member symbol.`);
+      }
+      const memberOwner = base.hasTypeSymbol ? base.type : base.dealias();
+      if (member.ownerSymbol !== memberOwner) {
+        throw new Error(`${formatSymbolName(member)} is not a member of ${formatSymbolName(base)}.`);
+      }
+    }
+  }
+  function notifySymbolCreated(symbol) {
+    effect(oldRefkeys => {
+      if (symbol.refkeys) {
+        debug.trace(TracePhase.resolve.pending, () => `Notifying resolutions for ${formatRefkeys(symbol.refkeys)}.`);
+      }
+      if (oldRefkeys) {
+        for (const refkey of oldRefkeys) {
+          if (!symbol.refkeys.includes(refkey)) {
+            // remove the old refkey from the known declarations
+            knownDeclarations.delete(refkey);
+
+            // reset any waiting declarations
+            if (waitingDeclarations.has(refkey)) {
+              const signal = waitingDeclarations.get(refkey);
+              signal.value = undefined;
+            }
+          }
+        }
+      }
+      for (const refkey of symbol.refkeys) {
+        // notify those waiting for this refkey
+        knownDeclarations.set(refkey, symbol);
+        if (waitingDeclarations.has(refkey)) {
+          const signal = waitingDeclarations.get(refkey);
+          signal.value = symbol;
+        }
+        const scope = symbol.scope;
+        if (!scope) {
+          continue;
+        }
+
+        // notify those waiting for this symbol name
+        const waitingScope = waitingSymbolNames.get(scope);
+        if (waitingScope) {
+          const waitingName = waitingScope.get(symbol.name);
+          if (waitingName) {
+            waitingName.value = symbol;
+          }
+        }
+      }
+      return [...symbol.refkeys];
+    }, undefined, {
+      debug: {
+        name: "binder:notifySymbolCreated",
+        type: "binder"
+      }
+    });
+  }
+}
+
+/**
+ * Resolve a refkey in the current scope. Returns a Ref for the resolution result.
+ * The value of the ref will be undefined if the identifier hasn't been resolved yet.
+ *
+ * @remarks
+ *
+ * This API may return a ref for undefined, but that does not mean that the symbol is
+ * not found. The symbol you're looking for may not have been declared yet. When the symbol
+ * is declared, the ref will be updated with the resolution result.
+ */
+export function resolve(refkey, options = {}) {
+  const scope = useScope();
+  const memberScope = useMemberContext();
+  const binder = scope?.binder ?? memberScope?.ownerSymbol.binder;
+  if (!binder) {
+    throw new Error("Can't resolve refkey without a binder");
+  }
+  const result = binder.resolveDeclarationByKey(scope, refkey, options);
+  let diagnosticHandle = 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;
+}
+
+/**
+ * Get a ref to the symbol for the given refkey using the current binder. The
+ * value of the ref will be undefined when no symbol with that refkey has been
+ * created.
+ *
+ * @remarks
+ *
+ * This API may return a ref for undefined, but that does not mean that the symbol is
+ * not found. The symbol you're looking for may not have been declared yet. When the symbol
+ * is declared, the ref will be updated with the symbol.
+ */
+export function symbolForRefkey(refkey) {
+  const binder = useBinder();
+  if (!binder) {
+    throw new Error("Can't resolve refkey without a binder");
+  }
+  return binder.getSymbolForRefkey(refkey);
+}
+const createSymbolsSymbol = Symbol();
+export function getSymbolCreator(creator) {
+  return creator[createSymbolsSymbol];
+}
+export function getSymbolCreatorSymbol() {
+  return createSymbolsSymbol;
+}
+
+/**
+ * An object that can register symbols into a binder. Pass instances to the
+ * `externals` prop of `<Output>` to make library symbols resolvable.
+ *
+ * @remarks
+ * `SymbolCreator` is a low-level core mechanism for eager symbol registration.
+ * The recommended pattern for language packages is lazy self-registration:
+ * implement `[TO_SYMBOL]()` on descriptors to call `useBinder()`, create and
+ * cache symbols per binder via a `WeakMap`, and register them into the
+ * appropriate scope automatically. This approach does not require `externals`.
+ * See the C# package's `createLibrary()` for a reference implementation.
+ *
+ * See {@link TO_SYMBOL} and {@link REFKEYABLE}.
+ */
+//# sourceMappingURL=binder.js.map