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

package/docs/symbols-and-scopes.md

@@ -0,0 +1,180 @@
+# Symbols & Scopes
+
+Alloy's symbol system models declarations, references, and name resolution — the same concepts found in compilers, adapted for code generation.
+
+## Overview
+
+The [**binder**](api/contexts/Binder-context.md) is the central registry, set up by [`<Output>`](api/components/Output.md). It tracks scopes and symbols. Scopes form a tree mirroring the output structure; each symbol lives in a scope and is identified by one or more [**refkeys**](api/types/Refkey.md). When a refkey appears in JSX, the binder resolves it to the target symbol and computes the scope path between reference and declaration so language packages can emit the correct reference syntax.
+
+## Symbols
+
+[`OutputSymbol`](api/types/OutputSymbol.md) is the base class. Key properties: reactive `name` (subject to name policies), `refkeys`, `scope`, and optional member spaces.
+
+Language packages subclass `OutputSymbol` to add language-specific properties (e.g., accessibility, static/abstract flags).
+
+`BasicSymbol` is a concrete subclass from core with "static" and "instance" member spaces — suitable for simple languages or prototyping.
+
+### Declaring Symbols
+
+[`<Declaration>`](api/components/Declaration.md) creates a `BasicSymbol` by default:
+
+```tsx
+const fnKey = refkey();
+<Declaration name="myFunction" refkey={fnKey}>
+  {/* content */}
+</Declaration>;
+```
+
+For custom symbol types, pass a pre-created symbol via `symbol`:
+
+```tsx
+const sym = createSymbol(MyCustomSymbol, namekey, scope.symbols, options);
+<Declaration symbol={sym}>{/* content */}</Declaration>;
+```
+
+See [`OutputSymbol`](api/types/OutputSymbol.md) and [`OutputSymbolOptions`](api/types/OutputSymbolOptions.md) for parameter details.
+
+Language packages wrap [`<Declaration>`](api/components/Declaration.md) with their own components that create language-specific symbol types.
+
+### Member Spaces
+
+Symbols can have member spaces holding child symbols. Override `static memberSpaces` to declare the space keys for your symbol type (e.g., `["static", "instance"]`). [`<MemberScope>`](api/components/MemberScope.md) enters a member space; [`<MemberDeclaration>`](api/components/MemberDeclaration.md) declares within it.
+
+Member spaces ([`OutputMemberSpace`](api/types/OutputSpace.md)) belong to symbols; declaration spaces ([`OutputDeclarationSpace`](api/types/OutputSpace.md)) belong to scopes. Together they form the [`OutputSpace`](api/types/OutputSpace.md) type. Symbols register via the constructor `space` parameter.
+
+### Typed Symbols
+
+Symbols support a type-symbol relationship through three properties:
+
+- **`isTyped`**: set at construction when `OutputSymbolOptions.type` is provided. Not reactive.
+- **`type`**: reactive getter/setter for the type symbol reference. The setter accepts `OutputSymbol` or `Ref<OutputSymbol>` (for deferred resolution) and auto-dealiases. When `isTyped` is true but `type` is not yet resolved, the symbol's members are unavailable until the type arrives.
+- **`hasTypeSymbol`**: derived reactive getter (`this.type !== undefined`).
+
+Language packages can add their own symbol properties to control resolution behavior.
+
+### Member Resolution
+
+The default `resolveMemberByName()` performs:
+
+1. If `isTyped`, delegate to `type.resolveMemberByName()` (or return `undefined` if type not yet available).
+2. Otherwise, search member spaces in order for a matching name.
+
+There is no privacy or reachability check in the default resolver. When a language needs access-control filtering, provide a custom `memberResolver` callback. **Return `void` to accept** the member; **throw an error to reject** it. See [`MemberResolver`](api/types/MemberResolver.md) for details.
+
+## Scopes
+
+`OutputScope` is the base class, forming a tree. Each scope has parent/children, one or more **declaration spaces** (named collections of symbols), and is either **lexical** (own declarations) or a **member** scope (exposing an owner symbol's members).
+
+Language packages subclass `OutputScope` for custom declaration spaces and behavior (e.g., import tracking, namespace resolution).
+
+`BasicScope` is a concrete subclass from core with a single "symbols" space — suitable for simple languages or prototyping.
+
+[`<Scope>`](api/components/Scope.md) creates a `BasicScope` by default. Language packages pass custom scope instances via the `value` prop. Use [`createScope()`](api/contexts/Scope-context.md) to construct one.
+
+### OutputScope Members
+
+| Member              | Type                                  | Description                                                                                                                                    |
+| ------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`              | `string` (reactive)                   | Descriptive name (used in debugging).                                                                                                          |
+| `parent`            | `OutputScope \| undefined` (reactive) | Parent scope, or `undefined` for roots.                                                                                                        |
+| `children`          | `Set<OutputScope>` (readonly)         | Directly nested child scopes.                                                                                                                  |
+| `binder`            | `Binder \| undefined` (readonly)      | Binder that owns this scope.                                                                                                                   |
+| `metadata`          | `Record<string, unknown>`             | The property itself is not reactive; the returned object is a reactive plain object (`Record<string, unknown>` wrapped with Vue `reactive()`). |
+| `spaceFor(key)`     | `OutputSpace \| undefined`            | Returns the declaration space for `key`. `undefined` if `key` is not in `declarationSpaces`.                                                   |
+| `declarationSpaces` | `string[]` (static)                   | Space keys defined by this scope subclass.                                                                                                     |
+
+### Declaration Spaces
+
+A scope can have multiple declaration spaces. Override `static declarationSpaces` to declare the space keys for your scope type. Core's `BasicScope` provides a single "symbols" space; language packages define their own — e.g., a language might define separate "types" and "values" spaces.
+
+## Refkeys
+
+A [`Refkey`](api/types/Refkey.md) uniquely identifies a symbol. Created with [`refkey()`](api/functions/refkey.md):
+
+```ts
+const myClassKey = refkey();
+const myClassKey = refkey("MyClass"); // stable seed
+```
+
+**Composite:** `refkey(a, b)` — deterministic key from multiple arguments.
+**Member:** [`memberRefkey(baseKey, "member")`](api/functions/memberRefkey.md) — access a member of another symbol.
+
+When a `Refkey` appears as a JSX child, the binder resolves it and emits the appropriate reference. If resolution fails, [`unresolvedRefkey(refkey)`](api/functions/unresolvedRefkey.md) returns a placeholder.
+
+A [`Namekey`](api/types/Namekey.md) is a refkey variant that carries a name and options. Use [`namekey(name, options?)`](api/functions/namekey.md) for names that must bypass the name policy:
+
+```ts
+const name = namekey("$special", { ignoreNamePolicy: true });
+```
+
+## Binder
+
+The central resolution engine. Tracks all scopes and symbols, resolves refkeys by searching up the scope tree, computes scope paths (`pathUp`/`pathDown`), and handles member resolution chains.
+
+Set up by [`<Output>`](api/components/Output.md), available via [`BinderContext`](api/contexts/Binder-context.md). Scopes inherit binder from parent.
+
+### [`resolve(refkey, options?)`](api/functions/resolve.md)
+
+Primary API for resolving a refkey from a component. Returns a reactive `Ref<`[`ResolutionResult`](api/types/ResolutionResult.md)`>`. Generics narrow to language-specific types:
+
+```ts
+const result = resolve<MyLangScope, MyLangSymbol>(myRefkey);
+```
+
+The [`ResolutionResult`](api/types/ResolutionResult.md) contains the resolved symbol, common ancestor scope, scope paths, and member path. Language packages use `pathDown` to decide how to render a reference.
+
+## Symbol Flow
+
+Symbols can be **emitted** upward and **taken** by ancestors:
+
+- [**`emitSymbol(symbol)`**](api/functions/emitSymbol.md) — emit from current component.
+- [**`takeSymbols(cb?)`**](api/functions/takeSymbols.md) — capture emitted descendants. Returns a reactive set.
+- [**`moveTakenMembersTo(symbol)`**](api/functions/moveTakenMembersTo.md) — take descendants and move as members.
+- [**`createSymbolSlot()`**](api/functions/createSymbolSlot.md) — wrapper component capturing emitted symbols in a subtree.
+
+Example: a variable declaration component wraps its type annotation in a symbol slot, then associates captured type symbols with the variable's symbol.
+
+## Name Policies
+
+`NamePolicy` transforms names by element type (e.g., camelCase for variables, PascalCase for classes). Set on [`<Output>`](api/components/Output.md), applied automatically. Symbols can opt out with `ignoreNamePolicy`.
+
+Name conflict resolution is per-language (e.g., a language package might append `_1`, `_2` to conflicting imports).
+
+## Extending Symbols and Scopes
+
+Custom reactive properties use Vue's `track()` / `trigger()`:
+
+```ts
+import { track, trigger, TrackOpTypes, TriggerOpTypes } from "@alloy-js/core";
+
+class CSharpSymbol extends OutputSymbol {
+  #isStatic = false;
+  get isStatic() {
+    track(this, TrackOpTypes.GET, "isStatic");
+    return this.#isStatic;
+  }
+  set isStatic(value: boolean) {
+    const old = this.#isStatic;
+    this.#isStatic = value;
+    trigger(this, TriggerOpTypes.SET, "isStatic", value, old);
+  }
+}
+```
+
+## External Libraries
+
+Language packages model external dependencies as scope/symbol trees outside rendered output. [`REFKEYABLE`](api/variables/REFKEYABLE.md) lets objects produce a refkey for resolution. [`TO_SYMBOL`](api/variables/TO_SYMBOL.md) enables lazy symbol creation — the binder calls `[TO_SYMBOL]()` on first reference.
+
+Typical pattern:
+
+1. Describe the library structure with a descriptor object.
+2. Implement `[REFKEYABLE]()` (returns a refkey) and `[TO_SYMBOL]()` (creates the symbol) on each descriptor.
+3. Cache symbols per binder in a `WeakMap<Binder, Symbol>`.
+4. Use `lazyMemberInitializer` on container types to initialize members lazily when first accessed.
+
+```ts
+const lib = createLibrary("my-lib", { SomeType: { kind: "type", members: { ... } } });
+<>{lib.SomeType}</> // symbol created lazily on first reference
+```
+
+Library descriptors self-register on demand — no additional wiring to `<Output>` is needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.23.0-dev.12",
+  "version": "0.23.0-dev.15",
   "description": "",
   "repository": {
     "type": "git",
@@ -43,8 +43,12 @@
   "browser": {
     "./dist/src/host/alloy-host.js": "./dist/src/host/alloy-host.browser.js",
     "./src/host/alloy-host.ts": "./src/host/alloy-host.browser.ts",
+    "./dist/src/host/node-host.js": "./dist/src/host/node-host.browser.js",
+    "./src/host/node-host.ts": "./src/host/node-host.browser.ts",
     "./dist/src/inspect.js": "./dist/src/inspect.browser.js",
     "./src/inspect.ts": "./src/inspect.browser.ts",
+    "./dist/src/debug/source-map.js": "./dist/src/debug/source-map.browser.js",
+    "./src/debug/source-map.ts": "./src/debug/source-map.browser.ts",
     "./dist/src/devtools/devtools-server.js": "./dist/src/devtools/devtools-server.browser.js",
     "./src/devtools/devtools-server.ts": "./src/devtools/devtools-server.browser.ts"
   },
@@ -62,8 +66,8 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.4",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.5",
+    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.2",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "concurrently": "^9.2.0",
@@ -73,7 +77,7 @@
   },
   "type": "module",
   "scripts": {
-    "generate-docs": "api-extractor run",
+    "generate-docs": "api-extractor run && api-extractor run -c api-extractor.testing.json",
     "build": "alloy build --with-dev && pnpm run generate-docs",
     "clean": "rimraf dist/ .temp/",
     "test": "vitest run",

package/src/binder.ts

@@ -102,7 +102,9 @@ export interface Binder {
  * * **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**: [foo, bar], because we resolved a member symbol and these are the symbols that lead from the base declaration to the member symbol.
+ * * **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.
  */
 export interface ResolutionResult<
   TScope extends OutputScope,
@@ -149,8 +151,8 @@ export interface ResolutionResult<
   commonScope: TScope | undefined;
 
   /**
-   * When resolving a member symbol, this is the path of symbols that lead from
-   * the lexical declaration to the member symbol.
+   * Member symbols from the lexical declaration (exclusive) to the resolved symbol
+   * (inclusive). Empty when resolving a non-member symbol.
    */
   memberPath: TSymbol[];
 }
@@ -164,6 +166,36 @@ export interface MemberDescriptor {
   isMemberAccess: boolean;
 }
 
+/**
+ * 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);
+ *   }
+ * };
+ * ```
+ */
 export interface NameConflictResolver {
   (name: string, symbols: OutputSymbol[]): void;
 }
@@ -187,7 +219,28 @@ export interface MemberResolutionContext<TScope extends OutputScope> {
 }
 
 /**
+ * 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.
  */
 export interface MemberResolver<
   TScope extends OutputScope,
@@ -209,6 +262,30 @@ export interface BinderOptions {
   nameConflictResolver?: NameConflictResolver;
 }
 
+/**
+ * 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<TScope extends OutputScope, Args extends unknown[]>(
   ctor: new (...args: Args) => TScope,
   ...args: Args
@@ -218,6 +295,19 @@ export function createScope<TScope extends OutputScope, Args extends unknown[]>(
   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<
   TSymbol extends OutputSymbol,
   Args extends unknown[],
@@ -803,6 +893,20 @@ export function getSymbolCreatorSymbol(): typeof createSymbolsSymbol {
   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}.
+ */
 export interface SymbolCreator {
   [createSymbolsSymbol](binder: Binder): void;
 }

package/src/components/Block.tsx

@@ -31,6 +31,18 @@ export interface BlockProps {
  * Create an indented block of source text. The block has `opener` text which is
  * added prior to the block, which defaults to `"{"`, and `closer` text which is
  * added after the block, which defaults to `"}"`.
+ *
+ * @remarks
+ *
+ * When `children` is empty, `Block` renders as `{}` (opener immediately followed
+ * by closer) with no indented content — no explicit empty check is needed before
+ * passing children.
+ *
+ * @example
+ * ```tsx
+ * // Safe even when props.members is empty — renders `{}`
+ * <Block>{props.members}</Block>
+ * ```
  */
 export function Block(props: BlockProps) {
   const ContentSlot = createContentSlot();

package/src/components/List.tsx

@@ -39,7 +39,17 @@ export interface BaseListProps {
   ender?: Children;
 
   /**
-   * Place the join punctuation at the end, but without a line break.
+   * Place the join punctuation at the end, without a line break. The punctuation
+   * is emitted unconditionally in flat and broken modes.
+   *
+   * To add trailing punctuation only in broken mode, use `ender` with `<ifBreak>`
+   * inside a `<group>` with a non-hardline joiner (e.g. `line`):
+   *
+   * ```tsx
+   * <group>
+   *   <List comma line ender={<ifBreak>,</ifBreak>}>...</List>
+   * </group>
+   * ```
    */
   enderPunctuation?: boolean;
 }

package/src/components/MemberDeclaration.tsx

@@ -60,16 +60,16 @@ export type MemberDeclarationProps =
  *
  * This component must be called in one of two ways: with a name and an optional
  * refkey, or else passing in the symbol. When called with a name and refkey, a
- * symbol will be created in the current scope (provided by
- * {@link MemberDeclarationContext}) with that name and refkey. If a refkey is not
- * provided, `refkey(props.name)` is used.
+ * `BasicSymbol` will be created in the current member space. When called with a
+ * `name`, the owning scope must be a `BasicScope`; for custom scope/symbol
+ * types, pass a pre-created `symbol` instead.
  *
  * When called with a symbol, that symbol is merely exposed via
- * {@link MemberDeclarationContext}. It is assumed that the caller of this component
- * has created the symbol with the `createSymbol` API on the
- * {@link BinderContext}.
+ * {@link MemberDeclarationContext} (not {@link DeclarationContext}). Use
+ * {@link MemberName} (not `<Name />`) to render the declared member's name.
  *
  * @see {@link BinderContext}
+ * @see {@link MemberName}
  */
 export function MemberDeclaration(props: MemberDeclarationProps) {
   const binder = useContext(BinderContext);

package/src/components/MemberName.tsx

@@ -1,6 +1,12 @@
 import { useContext } from "../context.js";
 import { MemberDeclarationContext } from "../context/member-declaration.js";
 
+/**
+ * Renders the name of the current member declaration from
+ * {@link MemberDeclarationContext}. Use this inside a
+ * {@link MemberDeclaration} component instead of `<Name />`, which reads from
+ * the top-level {@link DeclarationContext}.
+ */
 export function MemberName() {
   const declSymbol = useContext(MemberDeclarationContext);
   if (!declSymbol) {

package/src/components/MemberScope.tsx

@@ -56,6 +56,11 @@ export type MemberScopeProps =
  * like. In some languages, this scope may provide symbols which are can be
  * referenced lexically, but in other languages, these members may not be in
  * scope and instead must be referenced via the owner symbol itself.
+ *
+ * When called with `name` (without `value`), this delegates to `<Scope>` which
+ * creates a `BasicScope`. The same restriction applies: the parent scope must
+ * be a `BasicScope`. For custom scope types, create your scope and pass it via
+ * the `value` prop.
  */
 export function MemberScope(props: MemberScopeProps) {
   if ("value" in props) {

package/src/components/Output.tsx

@@ -1,6 +1,7 @@
 import {
   createOutputBinder,
   getSymbolCreator,
+  NameConflictResolver,
   SymbolCreator,
 } from "../binder.js";
 import { BinderContext } from "../context/binder.js";
@@ -28,8 +29,10 @@ export interface OutputProps extends PrintTreeOptions {
 
   /**
    * Policy for handling multiple symbols declared with the same name.
+   *
+   * @see {@link NameConflictResolver}
    */
-  nameConflictResolver?: (name: string, symbols: any[]) => void;
+  nameConflictResolver?: NameConflictResolver;
 
   /**
    * The base path for the output contents. Defaults to "."

package/src/components/Scope.tsx

@@ -47,6 +47,12 @@ export type ScopeProps = ScopePropsWithValue | ScopePropsWithInfo;
  * Declare a scope for this component's children. Any symbols and scopes
  * declared in the children of this component will be in this scope.
  *
+ * @remarks
+ *
+ * When called with `name` (without `value`), this creates a `BasicScope`. The
+ * parent scope must also be a `BasicScope`; for custom scope types, create your
+ * scope and pass it via the `value` prop instead.
+ *
  * @see {@link ScopeContext}
  */
 export function Scope(props: ScopeProps) {

package/src/components/SourceFile.tsx

@@ -17,6 +17,11 @@ export interface SourceFileProps extends PrintTreeOptions {
 
   /**
    * The type of contents in this file.
+   *
+   * @remarks
+   * This is a metadata hint only. It does not trigger formatting or content
+   * processing. The value is forwarded to debug tooling and the
+   * `ContentOutputFile` output metadata.
    */
   filetype: string;
 
@@ -28,8 +33,23 @@ export interface SourceFileProps extends PrintTreeOptions {
    */
   reference?: ComponentDefinition<{ refkey: Refkey }>;
   /**
-   * The header of the file. This is rendered before the contents of the file.
-   * This is useful for adding license headers or other metadata to the file.
+   * Content rendered before the file body, separated from it by a hard line
+   * break. The separator is emitted whenever `header` is not `undefined` —
+   * including when it is an empty string or a component that renders nothing.
+   * To suppress both the header and the separator, omit this prop entirely.
+   *
+   * @example
+   * ```tsx
+   * // Omitting `header` suppresses both header and separator:
+   * <SourceFile filetype="txt" path="output/data.txt">
+   *   {children}
+   * </SourceFile>
+   *
+   * // An empty string still emits the separator newline:
+   * <SourceFile filetype="txt" path="output/data.txt" header="">
+   *   {children}
+   * </SourceFile>
+   * ```
    */
   header?: Children;
 }

package/src/context/binder.ts

@@ -14,6 +14,10 @@ import type { Output } from "../components/Output.js";
 export const BinderContext: ComponentContext<Binder> =
   createNamedContext("Binder");
 
+/**
+ * Returns the current {@link Binder} from context, or `undefined` if no
+ * binder is available. The binder is provided by the {@link Output} component.
+ */
 export function useBinder() {
   return useContext(BinderContext);
 }

package/src/context/format-options.ts

@@ -3,10 +3,23 @@ import { PrintTreeOptions } from "../render.js";
 
 export interface CommonFormatOptions extends PrintTreeOptions {}
 
+/**
+ * Base format options provider and consumer for all file types. Language
+ * packages create their own via {@link createFormatOptionsContextFor}.
+ */
 export const { Provider: FormatOptions, useFormatOptions } =
   createFormatOptionsContextFor<CommonFormatOptions>("*");
 
-/** Create a format options context for a specific file type */
+/**
+ * Create a format options context for a specific file type. Returns a
+ * `Provider` component and a `useFormatOptions` hook.
+ *
+ * @remarks
+ *
+ * Merge precedence: `defaults` (lowest) → Provider `value` → `overrides`
+ * argument to `useFormatOptions()` (highest). Undefined override values are
+ * ignored.
+ */
 export function createFormatOptionsContextFor<T>(
   filetype: string,
   defaults?: T,

package/src/context/scope.ts

@@ -8,6 +8,10 @@ import type { OutputScope } from "../symbols/output-scope.js";
 export const ScopeContext: ComponentContext<OutputScope> =
   createNamedContext("Scope");
 
+/**
+ * Returns the current {@link OutputScope} from context. Must be called inside
+ * a component that is a descendant of a `<Scope>` provider.
+ */
 export function useScope() {
   return useContext(ScopeContext)!;
 }

package/src/context/source-directory.ts

@@ -9,5 +9,14 @@ export interface SourceDirectoryContext {
   path: string;
 }
 
+/**
+ * Always provided by `<Output>` — `useContext(SourceDirectoryContext)` is
+ * never `undefined` inside an `<Output>` tree. At the root of the tree,
+ * `path` equals the `basePath` prop on `<Output>` (default `"./"`); nested
+ * `<SourceDirectory>` components update `path` relative to their parent.
+ *
+ * @see {@link Output}
+ * @see {@link SourceDirectory}
+ */
 export const SourceDirectoryContext: ComponentContext<SourceDirectoryContext> =
   createNamedContext("SourceDirectory");

package/src/debug/cli.ts

@@ -1,6 +1,7 @@
 import Table from "cli-table3";
 import pc from "picocolors";
 import { contextsByKey } from "../context.js";
+import { stdoutWrite } from "../host/node-host.js";
 import { getContext, untrack } from "../reactivity.js";
 import { isReactiveTarget } from "./effects.js";
 
@@ -143,7 +144,7 @@ export function debugStack() {
         currentContext.componentOwner &&
         currentContext.componentOwner.component.name !== "Provider"
       ) {
-        process.stdout.write(
+        stdoutWrite(
           style.component.name(currentContext.componentOwner.component.name) +
             "\n",
         );
@@ -164,7 +165,7 @@ export function debugStack() {
           : pc.gray("(none)"),
         ]);
 
-        process.stdout.write(table.toString() + "\n\n");
+        stdoutWrite(table.toString() + "\n\n");
         foundContexts = [];
       }
 

package/src/debug/source-map.browser.ts

@@ -0,0 +1,30 @@
+/**
+ * Browser stub for source-map resolution.
+ *
+ * Source maps are not resolved in the browser — all functions pass through
+ * their inputs unchanged.
+ */
+
+import type { SourceLocation } from "../devtools/devtools-protocol.js";
+
+export function loadSourceMapSupport() {
+  // no-op in browser
+}
+
+export function getRealPath(fileName: string): string {
+  return fileName;
+}
+
+export function resolveSourceMap(
+  fileName: string,
+  line: number,
+  col: number,
+): { fileName: string; line: number; col: number } {
+  return { fileName, line, col };
+}
+
+export function resolveComponentSource(
+  source: SourceLocation | undefined,
+): SourceLocation | undefined {
+  return source;
+}