@alloy-js/core 0.23.0-dev.12 → 0.23.0-dev.15

package/temp/api.json

@@ -1296,7 +1296,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!BaseListProps#enderPunctuation:member",
-              "docComment": "/**\n * Place the join punctuation at the end, but without a line break.\n */\n",
+              "docComment": "/**\n * Place the join punctuation at the end, without a line break. The punctuation\n * is emitted unconditionally in flat and broken modes.\n *\n * To add trailing punctuation only in broken mode, use `ender` with `<ifBreak>`\n * inside a `<group>` with a non-hardline joiner (e.g. `line`):\n *\n * ```tsx\n * <group>\n *   <List comma line ender={<ifBreak>,</ifBreak>}>...</List>\n * </group>\n * ```\n *\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -2526,7 +2526,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!Block:function(1)",
-          "docComment": "/**\n * Create an indented block of source text. The block has `opener` text which is\n * added prior to the block, which defaults to `\"{\"`, and `closer` text which is\n * added after the block, which defaults to `\"}\"`.\n */\n",
+          "docComment": "/**\n * Create an indented block of source text. The block has `opener` text which is\n * added prior to the block, which defaults to `\"{\"`, and `closer` text which is\n * added after the block, which defaults to `\"}\"`.\n *\n * @remarks\n *\n *\n *\n * When `children` is empty, `Block` renders as `{}` (opener immediately followed\n * by closer) with no indented content — no explicit empty check is needed before\n * passing children.\n *\n * @example\n * ```tsx\n * // Safe even when props.members is empty — renders `{}`\n * <Block>{props.members}</Block>\n * ```\n *\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -5537,7 +5537,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!createFormatOptionsContextFor:function(1)",
-          "docComment": "/**\n * Create a format options context for a specific file type\n */\n",
+          "docComment": "/**\n * Create a format options context for a specific file type. Returns a\n * `Provider` component and a `useFormatOptions` hook.\n *\n * @remarks\n *\n *\n *\n * Merge precedence: `defaults` (lowest) → Provider `value` → `overrides`\n * argument to `useFormatOptions()` (highest). Undefined override values are\n * ignored.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -5900,7 +5900,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!createNamePolicy:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Creates a name policy that transforms symbol names based on element kind.\n *\n * @remarks\n *\n *\n * `element` identifies the kind of declaration (e.g., `\"value\"`, `\"type\"`).\n * The set of valid element strings is defined by the language package.\n *\n * When `element` is `undefined` (outside a declaration context), {@link NamePolicy.getName}\n * and {@link NamePolicy.for} short-circuit and return the original name unchanged — the\n * namer callback is **not** invoked. The namer therefore always receives a defined `T`.\n * This means names outside a declaration context cannot be transformed by the policy.\n *\n * @example\n * ```ts\n * const policy = createNamePolicy((name, element) => {\n *   if (element === \"value\") return toCamelCase(name);\n *   if (element === \"type\")  return toPascalCase(name);\n *   return name;\n * });\n * <Output namePolicy={policy}>...</Output>\n * ```\n *\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -5916,7 +5916,7 @@
             },
             {
               "kind": "Content",
-              "text": "(name: string, elements: T) => string"
+              "text": "(name: string, element: T) => string"
             },
             {
               "kind": "Content",
@@ -6280,7 +6280,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!createScope:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Construct a scope instance and register it with devtools. Prefer this over\n * calling `new` directly so that debugging tools can track the scope.\n *\n * @remarks\n *\n *\n *\n * Inside a component, obtain the current scope with `useScope()` and pass it\n * as the `parentScope` constructor argument so the new scope is wired into\n * the scope tree.\n *\n * @param ctor - The scope subclass constructor.\n *\n * @param args - Positional arguments forwarded directly to the scope\n * constructor; see {@link OutputScope} for the base-class constructor\n * signature.\n *\n * @example\n * ```tsx\n * function MyScope(props) {\n *   const parentScope = useScope();\n *   const scope = createScope(MyScope, \"scope-name\", parentScope);\n *   return <Scope value={scope}>{props.children}</Scope>;\n * }\n * ```\n *\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -6541,7 +6541,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!createSymbol:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Construct a symbol instance and register it with devtools. Prefer this over\n * calling `new` directly so that debugging tools can track the symbol.\n *\n * @remarks\n *\n *\n *\n * Binder registration (via `useBinder()` + `notifySymbolCreated()`) happens\n * inside the `OutputSymbol` constructor regardless of whether you use\n * `createSymbol` or `new`. This helper only adds devtools registration.\n *\n * @param ctor - The symbol subclass constructor.\n *\n * @param args - Arguments forwarded to the constructor.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -12274,7 +12274,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@alloy-js/core!LibrarySymbolReference:interface",
-          "docComment": "",
+          "docComment": "/**\n * An object that acts as a lazy reference to an external library symbol.\n * Implements {@link REFKEYABLE} and `[TO_SYMBOL]()`.\n *\n * Use {@link isLibrarySymbolReference} to test whether an unknown value is a\n * library symbol reference.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -13334,7 +13334,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!MemberDeclaration:function(1)",
-          "docComment": "/**\n * Declares a symbol in the current member scope for this component's children.\n *\n * @remarks\n *\n *\n *\n * This component must be called in one of two ways: with a name and an optional\n * refkey, or else passing in the symbol. When called with a name and refkey, a\n * symbol will be created in the current scope (provided by\n * {@link MemberDeclarationContext}) with that name and refkey. If a refkey is not\n * provided, `refkey(props.name)` is used.\n *\n * When called with a symbol, that symbol is merely exposed via\n * {@link MemberDeclarationContext}. It is assumed that the caller of this component\n * has created the symbol with the `createSymbol` API on the\n * {@link BinderContext}.\n *\n * @see\n *\n *  {@link BinderContext}\n */\n",
+          "docComment": "/**\n * Declares a symbol in the current member scope for this component's children.\n *\n * @remarks\n *\n *\n *\n * This component must be called in one of two ways: with a name and an optional\n * refkey, or else passing in the symbol. When called with a name and refkey, a\n * `BasicSymbol` will be created in the current member space. When called with a\n * `name`, the owning scope must be a `BasicScope`; for custom scope/symbol\n * types, pass a pre-created `symbol` instead.\n *\n * When called with a symbol, that symbol is merely exposed via\n * {@link MemberDeclarationContext} (not {@link DeclarationContext}). Use\n * {@link MemberName} (not `<Name />`) to render the declared member's name.\n *\n * @see\n *\n *  {@link BinderContext}\n *\n * @see\n *\n *  {@link MemberName}\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -13779,7 +13779,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!MemberName:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Renders the name of the current member declaration from\n * {@link MemberDeclarationContext}. Use this inside a\n * {@link MemberDeclaration} component instead of `<Name />`, which reads from\n * the top-level {@link DeclarationContext}.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -14079,7 +14079,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@alloy-js/core!MemberResolver:interface",
-          "docComment": "",
+          "docComment": "/**\n * A callback that performs access-control filtering during member resolution.\n *\n * @remarks\n *\n *\n *\n * When provided to {@link ResolveDeclarationByKeyOptions}, it entirely replaces\n * the default checks (ownership assertion and `isMemberSymbol` assertion).\n *\n * **Contract:**\n * - **Return `void`** to accept the member.\n * - **Throw an error** to reject the member — the error propagates to the caller,\n *   matching the behavior of the default checks.\n *\n * @example\n * ```ts\n * const resolver: MemberResolver<MyScope, MySymbol> = (owner, member, ctx) => {\n *   if (member.isPrivate && !ctx.isMemberAccess) {\n *     throw new Error(`${member.name} is not accessible here`);\n *   }\n * };\n * ```\n *\n * @see\n *\n *  {@link MemberResolutionContext} for available context properties.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -14219,7 +14219,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!MemberScope:function(1)",
-          "docComment": "/**\n * Declare a member scope, which is a lexical scope whose symbols are provided\n * by the owner symbol.\n *\n * @remarks\n *\n *\n *\n * This is used to create members of a symbol, e.g. for class members and the\n * like. In some languages, this scope may provide symbols which are can be\n * referenced lexically, but in other languages, these members may not be in\n * scope and instead must be referenced via the owner symbol itself.\n */\n",
+          "docComment": "/**\n * Declare a member scope, which is a lexical scope whose symbols are provided\n * by the owner symbol.\n *\n * @remarks\n *\n *\n *\n * This is used to create members of a symbol, e.g. for class members and the\n * like. In some languages, this scope may provide symbols which are can be\n * referenced lexically, but in other languages, these members may not be in\n * scope and instead must be referenced via the owner symbol itself.\n *\n * When called with `name` (without `value`), this delegates to `<Scope>` which\n * creates a `BasicScope`. The same restriction applies: the parent scope must\n * be a `BasicScope`. For custom scope types, create your scope and pass it via\n * the `value` prop.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -14509,7 +14509,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!memo:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Returns a getter caching the result of `fn`. Re-evaluates when reactive\n * dependencies change. See the [Reactivity docs](../../reactivity.md) for details.\n *\n * @param fn - Function to memoize.\n *\n * @param equal - Skip updates when value is unchanged.\n *\n * @param name - Debug label for traces.\n *\n * @returns  A zero-argument getter returning the cached value.\n *\n * @example\n * ```ts\n * const fullName = memo(() => `${first.value} ${last.value}`);\n * fullName(); // cached; re-evaluates when first or last changes\n * ```\n *\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -15040,7 +15040,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@alloy-js/core!NameConflictResolver:interface",
-          "docComment": "",
+          "docComment": "/**\n * A callable interface invoked by the binder when two or more symbols in the\n * same scope share a name. The resolver mutates symbol names to eliminate\n * conflicts (e.g., appending `_2`, `_3`).\n *\n * @remarks\n *\n *\n * The resolver is called with the shared `name` and all symbols in the scope\n * that have that original name. Rename a symbol by assigning to `symbol.name`.\n * Symbols with `ignoreNameConflict: true` are excluded. The default resolver\n * keeps the first symbol unchanged and renames subsequent ones\n * `originalName + \"_2\"`, `originalName + \"_3\"`, etc.\n *\n * Assigned names pass through the active name policy before being stored;\n * design suffixes to produce the correct final name after policy\n * transformation, or set `ignoreNamePolicy` on the symbol after resolution.\n *\n * Conflict detection is keyed on `originalName`\n * (see {@link OutputSymbol.originalName}). Symbols that differ in original\n * name but normalize to the same policy-applied name are never detected as\n * conflicting.\n *\n * @example\n * ```ts\n * const resolver: NameConflictResolver = (name, symbols) => {\n *   for (let i = 1; i < symbols.length; i++) {\n *     symbols[i].name = symbols[i].originalName + \"_\" + (i + 1);\n *   }\n * };\n * ```\n *\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -15410,7 +15410,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@alloy-js/core!NamePolicy#for:member(1)",
-              "docComment": "/**\n * Get a function that takes a name and applies the naming policy to it.\n */\n",
+              "docComment": "/**\n * Get a function that takes a name and applies the naming policy to it.\n * When `element` is `undefined`, returns an identity function.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -15456,7 +15456,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@alloy-js/core!NamePolicy#getName:member(1)",
-              "docComment": "/**\n * Apply the language policy to the provided name for the provided element\n * type.\n */\n",
+              "docComment": "/**\n * Apply the language policy to the provided name for the provided element type.\n * When `element` is `undefined`, returns `originalName` unchanged.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -15557,7 +15557,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@alloy-js/core!NamePolicyGetter:interface",
-          "docComment": "",
+          "docComment": "/**\n * A function that transforms a name according to a naming policy for a\n * specific element kind. Obtained from {@link NamePolicy.for}.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -15845,7 +15845,7 @@
         {
           "kind": "Class",
           "canonicalReference": "@alloy-js/core!OutputDeclarationSpace:class",
-          "docComment": "",
+          "docComment": "/**\n * A symbol table attached to an {@link OutputScope}. Holds lexical declarations\n * visible within that scope (e.g., \"types\" or \"values\" in a TypeScript module).\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -16101,7 +16101,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!OutputDirectory#path:member",
-              "docComment": "",
+              "docComment": "/**\n * Full path from the output root, e.g. `\"generated-client/src\"`. Do not prepend parent directory paths when walking the tree.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -16209,7 +16209,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!OutputFileBase#path:member",
-              "docComment": "",
+              "docComment": "/**\n * Full path from the output root, e.g. `\"generated-client/src/models.ext\"`. Do not prepend parent directory paths when walking the tree.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -16239,7 +16239,7 @@
         {
           "kind": "Class",
           "canonicalReference": "@alloy-js/core!OutputMemberSpace:class",
-          "docComment": "",
+          "docComment": "/**\n * A symbol table attached to an {@link OutputSymbol}. Holds member declarations\n * belonging to that symbol (e.g., \"static\" or \"instance\" members of a class).\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -16519,15 +16519,16 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!OutputProps#nameConflictResolver:member",
-              "docComment": "/**\n * Policy for handling multiple symbols declared with the same name.\n */\n",
+              "docComment": "/**\n * Policy for handling multiple symbols declared with the same name.\n *\n * @see\n *\n *  {@link NameConflictResolver}\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
                   "text": "nameConflictResolver?: "
                 },
                 {
-                  "kind": "Content",
-                  "text": "(name: string, symbols: any[]) => void"
+                  "kind": "Reference",
+                  "text": "NameConflictResolver",
+                  "canonicalReference": "@alloy-js/core!NameConflictResolver:interface"
                 },
                 {
                   "kind": "Content",
@@ -16681,7 +16682,7 @@
             {
               "kind": "Constructor",
               "canonicalReference": "@alloy-js/core!OutputScope:constructor(1)",
-              "docComment": "/**\n * Constructs a new instance of the `OutputScope` class\n */\n",
+              "docComment": "/**\n * Subclasses must forward all three positional arguments to `super`. See\n * {@link createScope} for the preferred instantiation path.\n *\n * @param name - A descriptive name for this scope (used in debugging and\n * diagnostics).\n *\n * @param parentScope - The parent scope in the scope tree, or `undefined`\n * for root scopes. Inside a component, obtain this via `useScope()`.\n *\n * @param options - Additional scope options; see {@link OutputScopeOptions}.\n *\n * @example\n * ```ts\n * class MyScope extends OutputScope {\n *   constructor(\n *     name: string,\n *     parent: OutputScope | undefined,\n *     options?: OutputScopeOptions,\n *   ) {\n *     super(name, parent, options);\n *   }\n * }\n *\n * // Inside a component:\n * const scope = createScope(MyScope, \"my-scope\", useScope());\n * ```\n *\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -16865,7 +16866,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@alloy-js/core!OutputScope.declarationSpaces:member",
-              "docComment": "",
+              "docComment": "/**\n * The declaration space keys for this scope type. Subclasses override this\n * to declare which declaration spaces are created on construction (e.g.,\n * `[\"types\", \"values\"]`).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -17134,7 +17135,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@alloy-js/core!OutputScope#spaceFor:member(1)",
-              "docComment": "/**\n * Get the declaration space for the given key.\n */\n",
+              "docComment": "/**\n * Get the declaration space for the given key (e.g., `\"types\"`, `\"values\"`).\n * Returns `undefined` when no space with that key exists on this scope.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -17362,7 +17363,7 @@
         {
           "kind": "TypeAlias",
           "canonicalReference": "@alloy-js/core!OutputSpace:type",
-          "docComment": "",
+          "docComment": "/**\n * A symbol table that belongs to either a scope (declaration space) or a symbol\n * (member space).\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -17398,7 +17399,7 @@
         {
           "kind": "Class",
           "canonicalReference": "@alloy-js/core!OutputSymbol:class",
-          "docComment": "/**\n * An output symbol is a named entity that can be referenced in your output\n * code.\n *\n * @remarks\n *\n *\n *\n * This class is the base implementation of symbol. Most languages will have\n * subtypes that provide additional metadata. Symbols are reactive values, so\n * you can observe changes to their properties in a reactive context.\n */\n",
+          "docComment": "/**\n * An output symbol is a named entity that can be referenced in your output\n * code.\n *\n * @remarks\n *\n *\n *\n * This is an abstract base class. Language packages must subclass it and\n * implement the abstract {@link OutputSymbol.copy | copy()} method, which\n * creates a clone that tracks the original's name and flags.\n *\n * Subtypes typically add language-specific properties (e.g., accessibility,\n * static/abstract flags). Symbols are reactive values, so you can observe\n * changes to their properties in a reactive context.\n *\n * To construct a scopeless external library symbol — one that resolves via\n * refkey but does not appear in any declaration space — pass `undefined` as\n * the `spaces` constructor argument and supply `{ binder }` in `options`.\n * See {@link OutputSymbolOptions} (`binder` option) and {@link TO_SYMBOL}.\n *\n * @example\n *\n *\n *\n * ```ts\n * import { createSymbol, OutputSymbol, OutputSpace } from \"@alloy-js/core\";\n *\n * class MySymbol extends OutputSymbol {\n *   copy() {\n *     // getCopyOptions() already includes binder\n *     const opts = this.getCopyOptions();\n *     const sym = createSymbol(MySymbol, this.name, undefined, opts);\n *     this.initializeCopy(sym);\n *     return sym;\n *   }\n * }\n *\n * // name: string | Namekey; spaces: OutputSpace | OutputSpace[] | undefined; options: OutputSymbolOptions\n * const sym = createSymbol(MySymbol, namekey, scope.symbols, { binder });\n *\n * // Construct a scopeless external library symbol (resolves via refkey only):\n * const extSym = createSymbol(MySymbol, namekey, undefined, { binder });\n * ```\n *\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -17493,7 +17494,7 @@
             {
               "kind": "Constructor",
               "canonicalReference": "@alloy-js/core!OutputSymbol:constructor(1)",
-              "docComment": "/**\n * Constructs a new instance of the `OutputSymbol` class\n */\n",
+              "docComment": "/**\n * Constructs a new instance of the `OutputSymbol` class\n *\n * @param name - The symbol name, or a {@link Namekey} carrying name and\n * options (e.g., `ignoreNamePolicy`).\n *\n * @param spaces - The declaration or member space(s) this symbol belongs to.\n * Pass `undefined` for scopeless external library symbols (see `binder` option).\n *\n * @param options - Additional symbol options (binder, refkeys, metadata,\n * type, name policy, etc.).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -17647,7 +17648,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@alloy-js/core!OutputSymbol#copy:member(1)",
-              "docComment": "/**\n * Makes a copy of this symbol which will update the name and flags\n * of the clone when the original symbol is updated.\n *\n * @remarks\n *\n *\n *\n * This is used to create a symbol that is a copy of this symbol, but\n * with a different scope. Changes to the copy will not affect the\n * original symbol, and changes to the original symbol's name and flags\n * will overwrite the copy's name and flags.\n *\n * @param newScope - The scope to use for the copy.\n */\n",
+              "docComment": "/**\n * Create a clone of this symbol whose name and flags reactively track the\n * original.\n *\n * @remarks\n *\n *\n *\n * Called by `SymbolTable.copyTo` during scope/space transfers.\n * Subclasses implement cloning logic and call `getCopyOptions` for\n * base options and `initializeCopy` to wire up member copying and\n * name tracking.\n *\n * **Space registration contract:** The returned clone must not be registered\n * in any space on exit. `copyToSpace()` calls this method and assigns the\n * space afterward.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -17728,7 +17729,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@alloy-js/core!OutputSymbol#copyToSpace:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Copy this symbol into the given space. Calls {@link OutputSymbol.copy} and places\n * the result in `space`, then returns the copy.\n *\n * @param space - The space to place the copy in.\n *\n * @returns  The copy of this symbol, now belonging to `space`.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -18054,7 +18055,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@alloy-js/core!OutputSymbol#initializeCopy:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Wires up reactive member-space copying and name tracking from this symbol\n * to its `copy`.\n *\n * @remarks\n *\n *\n *\n * Iterates each member space and calls `copyTo` on the corresponding space\n * on `copy`. Then installs a reactive watcher so that any future change to\n * `this.name` is immediately mirrored onto `copy.name`.\n *\n * **Must be called by every `copy()` override** before the override returns.\n * Pair with `getCopyOptions` to supply the base constructor options.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -18341,7 +18342,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@alloy-js/core!OutputSymbol.memberSpaces:member",
-              "docComment": "",
+              "docComment": "/**\n * The member space keys for this symbol type. Subclasses override this to\n * declare which member spaces are created on construction (e.g.,\n * `[\"static\", \"instance\"]`).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -18495,7 +18496,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@alloy-js/core!OutputSymbol#name:member",
-              "docComment": "/**\n * The name of this symbol.\n *\n *\n * @reactive\n */\n",
+              "docComment": "/**\n * The name of this symbol. Assigning to this property applies the active\n * name policy (unless `ignoreNamePolicy` is true) before storing the value.\n *\n *\n * @reactive\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -18953,7 +18954,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!OutputSymbolOptions#binder:member",
-              "docComment": "/**\n * The binder instance associated with this symbol. Symbol updates and changes\n * will be reported to this binder. This binder will be able to find this\n * symbol via its refkey and other means. Without a binder, this symbol will\n * be unbound, which means it cannot be referenced by refkey.\n */\n",
+              "docComment": "/**\n * The binder instance associated with this symbol. Symbol updates and changes\n * will be reported to this binder. This binder will be able to find this\n * symbol via its refkey and other means. Without a binder, this symbol will\n * be unbound, which means it cannot be referenced by refkey.\n *\n * @remarks\n *\n *\n *\n * When constructing an external library symbol, pass `{ binder }` here to\n * ensure the symbol is registered with the binder. See {@link TO_SYMBOL} for\n * the full implementation protocol.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -19035,7 +19036,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!OutputSymbolOptions#lazyMemberInitializer:member",
-              "docComment": "/**\n * Provide a function which lazy-initializes members when an enumeration of members are needed.\n */\n",
+              "docComment": "/**\n * Provide a function which lazy-initializes members the first time\n * `resolveMemberByName()` is called on this symbol. Called at most once.\n *\n * @remarks\n *\n *\n *\n * Only `resolveMemberByName()` triggers this callback — iterating\n * `OutputMemberSpace` directly does not. The callback fires regardless of\n * whether the symbol belongs to any scope, so it is safe to use on scopeless\n * external library symbols.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -21781,7 +21782,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@alloy-js/core!ResolutionResult:interface",
-          "docComment": "/**\n * A successful resolution of a refkey.\n *\n * @example\n *\n *\n *\n * Let's say we have the following scopes and symbols:\n *\n * ```\n * scope: global scope\n * ├── scope: namespace scope 1\n * │   └── symbol: foo\n * │       └── static members\n * │           └── symbol: bar\n * └── scope: namespace scope 2\n *    └── (resolve bar from here)\n * ```\n *\n *\n * When we resolve the refkey for `bar` from within `namespace scope 2`, we will get the following\n * resolution result:\n *\n * * **targetDeclaration**: symbol bar, the symbol we resolved.\n * * **commonScope**: global scope, because this is the most specific scope that contains both the declaration and the reference.\n * * **pathUp**: [namespace scope 2], because this is the scope between the reference and the common scope.\n * * **pathDown**: [namespace scope 1], because this is the scope between the common scope and the declaration\n * * **memberPath**: [foo, bar], because we resolved a member symbol and these are the symbols that lead from the base declaration to the member symbol.\n */\n",
+          "docComment": "/**\n * A successful resolution of a refkey.\n *\n * @example\n *\n *\n *\n * Let's say we have the following scopes and symbols:\n *\n * ```\n * scope: global scope\n * ├── scope: namespace scope 1\n * │   └── symbol: foo\n * │       └── static members\n * │           └── symbol: bar\n * └── scope: namespace scope 2\n *    └── (resolve bar from here)\n * ```\n *\n *\n * When we resolve the refkey for `bar` from within `namespace scope 2`, we will get the following\n * resolution result:\n *\n * * **targetDeclaration**: symbol bar, the symbol we resolved.\n * * **commonScope**: global scope, because this is the most specific scope that contains both the declaration and the reference.\n * * **pathUp**: [namespace scope 2], because this is the scope between the reference and the common scope.\n * * **pathDown**: [namespace scope 1], because this is the scope between the common scope and the declaration\n * * **memberPath**: [bar]\n * * **lexicalDeclaration**: foo\n * For deeper chains (e.g., foo.bar.baz where bar and baz are member symbols, foo is not): memberPath = [bar, baz], lexicalDeclaration = foo.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -21946,7 +21947,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!ResolutionResult#memberPath:member",
-              "docComment": "/**\n * When resolving a member symbol, this is the path of symbols that lead from\n * the lexical declaration to the member symbol.\n */\n",
+              "docComment": "/**\n * Member symbols from the lexical declaration (exclusive) to the resolved symbol\n * (inclusive). Empty when resolving a non-member symbol.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -22554,7 +22555,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!Scope:function(1)",
-          "docComment": "/**\n * Declare a scope for this component's children. Any symbols and scopes\n * declared in the children of this component will be in this scope.\n *\n * @see\n *\n *  {@link ScopeContext}\n */\n",
+          "docComment": "/**\n * Declare a scope for this component's children. Any symbols and scopes\n * declared in the children of this component will be in this scope.\n *\n * @remarks\n *\n *\n *\n * When called with `name` (without `value`), this creates a `BasicScope`. The\n * parent scope must also be a `BasicScope`; for custom scope types, create your\n * scope and pass it via the `value` prop instead.\n *\n * @see\n *\n *  {@link ScopeContext}\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -23424,7 +23425,7 @@
         {
           "kind": "Variable",
           "canonicalReference": "@alloy-js/core!SourceDirectoryContext:var",
-          "docComment": "",
+          "docComment": "/**\n * Always provided by `<Output>` — `useContext(SourceDirectoryContext)` is\n * never `undefined` inside an `<Output>` tree. At the root of the tree,\n * `path` equals the `basePath` prop on `<Output>` (default `\"./\"`); nested\n * `<SourceDirectory>` components update `path` relative to their parent.\n *\n * @see\n *\n *  {@link Output}\n *\n * @see\n *\n *  {@link SourceDirectory}\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -23783,7 +23784,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!SourceFileProps#filetype:member",
-              "docComment": "/**\n * The type of contents in this file.\n */\n",
+              "docComment": "/**\n * The type of contents in this file.\n *\n * @remarks\n *\n *\n * This is a metadata hint only. It does not trigger formatting or content\n * processing. The value is forwarded to debug tooling and the\n * `ContentOutputFile` output metadata.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -23810,7 +23811,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!SourceFileProps#header:member",
-              "docComment": "/**\n * The header of the file. This is rendered before the contents of the file.\n * This is useful for adding license headers or other metadata to the file.\n */\n",
+              "docComment": "/**\n * Content rendered before the file body, separated from it by a hard line\n * break. The separator is emitted whenever `header` is not `undefined` —\n * including when it is an empty string or a component that renders nothing.\n * To suppress both the header and the separator, omit this prop entirely.\n *\n * @example\n * ```tsx\n * // Omitting `header` suppresses both header and separator:\n * <SourceFile filetype=\"txt\" path=\"output/data.txt\">\n *   {children}\n * </SourceFile>\n *\n * // An empty string still emits the separator newline:\n * <SourceFile filetype=\"txt\" path=\"output/data.txt\" header=\"\">\n *   {children}\n * </SourceFile>\n * ```\n *\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -25039,7 +25040,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@alloy-js/core!SymbolCreator:interface",
-          "docComment": "",
+          "docComment": "/**\n * An object that can register symbols into a binder. Pass instances to the\n * `externals` prop of `<Output>` to make library symbols resolvable.\n *\n * @remarks\n *\n *\n * `SymbolCreator` is a low-level core mechanism for eager symbol registration.\n * The recommended pattern for language packages is lazy self-registration:\n * implement `[TO_SYMBOL]()` on descriptors to call `useBinder()`, create and\n * cache symbols per binder via a `WeakMap`, and register them into the\n * appropriate scope automatically. This approach does not require `externals`.\n * See the C# package's `createLibrary()` for a reference implementation.\n *\n * See {@link TO_SYMBOL} and {@link REFKEYABLE}.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -26869,7 +26870,7 @@
         {
           "kind": "Variable",
           "canonicalReference": "@alloy-js/core!TO_SYMBOL:var",
-          "docComment": "",
+          "docComment": "/**\n * Well-known symbol for the lazy-symbol-creation protocol used by external\n * library descriptors. Objects implementing `[TO_SYMBOL]()` are recognized as\n * {@link LibrarySymbolReference} values that can be passed anywhere a refkey\n * is accepted.\n *\n * @remarks\n *\n *\n *\n * Implement `[TO_SYMBOL]()` on a descriptor object to register it as a\n * referenceable library symbol. Inside the method:\n *\n * 1. Call {@link useBinder} to get the current binder context.\n * 2. Look up (or create) the symbol for that binder in a\n *    `WeakMap<object, OutputSymbol>` (use a sentinel object for the\n *    no-binder case, since `WeakMap` keys must be objects).\n * 3. On first creation, construct the symbol and register it into the\n *    appropriate space for your library, passing `{ binder }`\n *    (see {@link OutputSymbolOptions.binder}).\n *\n * The method is called by language package code each time the descriptor is\n * used as a reference (e.g. inside `ref()`). It is NOT called by the binder\n * itself.\n *\n * @example\n *\n *\n *\n * ```ts\n * const defaultKey = {};\n * const symbols = new WeakMap<object, MySymbol>();\n * const descriptor: LibrarySymbolReference = {\n *   [REFKEYABLE]() {\n *     return descriptor[TO_SYMBOL]().refkeys[0];\n *   },\n *   [TO_SYMBOL]() {\n *     const binder = useBinder();\n *     const key = binder ?? defaultKey;\n *     let sym = symbols.get(key);\n *     if (!sym) {\n *       sym = new MySymbol(\"SomeType\", space, { binder });\n *       symbols.set(key, sym);\n *     }\n *     return sym;\n *   },\n * };\n * ```\n *\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -27487,7 +27488,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!useBinder:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Returns the current {@link Binder} from context, or `undefined` if no\n * binder is available. The binder is provided by the {@link Output} component.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -27767,7 +27768,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!useScope:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Returns the current {@link OutputScope} from context. Must be called inside\n * a component that is a descendant of a `<Scope>` provider.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",

package/test/browser-build.test.ts

@@ -1,91 +1,84 @@
-import { execSync } from "child_process";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
 import { join } from "path";
+import { build, type Rolldown } from "vite";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
-const testDir = join(__dirname, ".temp", "vite-test-project");
+const tempDir = join(__dirname, ".temp", "browser-build-test");
+const entryFile = join(tempDir, "entry.js");
 
-describe("Browser Build Test", () => {
-  beforeAll(() => {
-    // Cleanup previous runs
-    if (existsSync(testDir)) {
-      rmSync(testDir, { recursive: true, force: true });
-    }
+/**
+ * Bundles `@alloy-js/core` for the browser using Vite and returns
+ * the concatenated output code.
+ *
+ * Uses the `browser` export condition from the package exports map,
+ * which resolves to the compiled browser entry. This requires the
+ * package to be built first (the CI pipeline and `pnpm build` handle
+ * this automatically).
+ */
+async function bundleForBrowser(): Promise<string> {
+  const result = await build({
+    configFile: false,
+    logLevel: "silent",
+    resolve: {
+      conditions: ["browser", "import"],
+    },
+    // Disable automatic process.env replacement so we can detect leaks
+    define: {},
+    build: {
+      write: false,
+      minify: false,
+      rollupOptions: {
+        input: entryFile,
+        output: { format: "es" },
+        // Disable tree-shaking so we catch process.* references in ANY
+        // code path, even if it would be removed in a production build.
+        treeshake: false,
+        external: (id) => {
+          // Bundle @alloy-js packages — these are what we're validating
+          if (id.startsWith("@alloy-js/")) return false;
+          // Bundle relative/absolute imports (intra-package)
+          if (id.startsWith(".") || id.startsWith("/")) return false;
+          // Externalize third-party deps (vue, pathe, picocolors, …)
+          return true;
+        },
+      },
+    },
+  });
 
-    // Create a temporary Vite project
-    mkdirSync(testDir, { recursive: true });
+  const output = (
+    Array.isArray(result) ?
+      result[0]
+    : result) as Rolldown.RolldownOutput;
+  const chunks = output.output.filter(
+    (o): o is Rolldown.OutputChunk => o.type === "chunk",
+  );
+  return chunks.map((c) => c.code).join("\n");
+}
 
-    execSync("npm init -y", { cwd: testDir });
-    execSync("npm install vite", { cwd: testDir });
-    execSync("npm install ../../..", { cwd: testDir });
+describe("browser build", () => {
+  beforeAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+    mkdirSync(tempDir, { recursive: true });
+    writeFileSync(entryFile, 'export * from "@alloy-js/core";\n');
+  });
 
-    // Create a minimal Vite app
-    writeFileSync(
-      join(testDir, "index.js"),
-      `
-        import { writeOutput } from "@alloy-js/core";
-        console.log("Alloy-js core imported successfully!", writeOutput);
-      `,
-    );
+  afterAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
 
-    writeFileSync(
-      join(testDir, "vite.config.js"),
-      `
-        import { defineConfig } from "vite";
-    
-        export default defineConfig({
-          build: {
-            outDir: "dist",
-            target: "esnext",
-          }
-        });
-      `,
-    );
+  it("should bundle for browser without Node.js polyfills", async () => {
+    const code = await bundleForBrowser();
 
-    // Create an index.html file
-    writeFileSync(
-      join(testDir, "index.html"),
-      `
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <title>Vite Test</title>
-      </head>
-      <body>
-        <script type="module" src="/index.js"></script>
-      </body>
-      </html>
-      `,
-    );
+    // The browser bundle must not reference the Node.js `process` global.
+    // If this fails, a file is using process.env / process.cwd / etc.
+    // without going through host/node-host.ts (or another browser-overridden module).
+    expect(code).not.toMatch(/\bprocess\./);
 
-    writeFileSync(
-      join(testDir, "package.json"),
-      JSON.stringify(
-        {
-          type: "module",
-          scripts: {
-            build: "vite build",
-          },
-        },
-        null,
-        2,
-      ),
-    );
+    // Should not contain static require("node:…") calls
+    expect(code).not.toMatch(/require\(\s*["']node:/);
   }, 30_000);
-
-  it("Vite should build successfully", () => {
-    // Run Vite build process and wait for completion
-    expect(() => {
-      execSync("npm run build", { cwd: testDir, stdio: "inherit" });
-    }).not.toThrow();
-  }, 10000);
-
-  afterAll(() => {
-    // Ensure testDir exists before attempting to remove it
-    if (existsSync(testDir)) {
-      rmSync(testDir, { recursive: true, force: true });
-    }
-  });
 });