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

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.9",
+  "version": "0.24.0-dev.1",
   "description": "",
   "repository": {
     "type": "git",
@@ -10,35 +10,45 @@
   "exports": {
     ".": {
       "browser": "./dist/src/index.browser.js",
+      "development": "./dist/dev/src/index.js",
       "import": "./dist/src/index.js"
     },
     "./jsx-runtime": {
       "types": "./dist/src/jsx-runtime.d.ts",
+      "development": "./dist/dev/src/jsx-runtime.js",
       "import": "./dist/src/jsx-runtime.js"
     },
     "./testing": {
+      "development": "./dist/dev/testing/index.js",
       "import": "./dist/testing/index.js"
     },
     "./testing/matchers": {
       "types": "./testing/vitest.d.ts"
     },
     "./stc": {
+      "development": "./dist/dev/src/components/stc/index.js",
       "import": "./dist/src/components/stc/index.js"
     },
     "./components": {
+      "development": "./dist/dev/src/components/index.js",
       "import": "./dist/src/components/index.js"
     },
     "./devtools": {
       "types": "./dist/src/devtools-entry.d.ts",
       "browser": "./dist/src/devtools-entry.browser.js",
+      "development": "./dist/dev/src/devtools-entry.js",
       "import": "./dist/src/devtools-entry.js"
     }
   },
   "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"
   },
@@ -56,8 +66,8 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
+    "@alloy-js/cli": "~0.23.0 || >= 0.24.0-dev.0",
+    "@alloy-js/rollup-plugin": "~0.1.1 || >= 0.1.2-dev.1",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "concurrently": "^9.2.0",
@@ -67,8 +77,8 @@
   },
   "type": "module",
   "scripts": {
-    "generate-docs": "api-extractor run",
-    "build": "alloy build && pnpm run generate-docs",
+    "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",
     "test:watch": "vitest -w",

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[],
@@ -643,54 +733,63 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   }
 
   function notifySymbolCreated(symbol: OutputSymbol): void {
-    effect<Refkey[]>((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);
+    effect<Refkey[]>(
+      (oldRefkeys) => {
+        if (symbol.refkeys) {
+          debug.trace(
+            TracePhase.resolve.pending,
+            () => `Notifying resolutions for ${formatRefkeys(symbol.refkeys)}.`,
+          );
+        }
 
-            // reset any waiting declarations
-            if (waitingDeclarations.has(refkey)) {
-              const signal = waitingDeclarations.get(refkey)!;
-              signal.value = undefined;
+        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;
-        }
+        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;
-        }
+          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;
+          // 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];
-    });
+        return [...symbol.refkeys];
+      },
+      undefined,
+      {
+        debug: {
+          name: "binder:notifySymbolCreated",
+          type: "binder",
+        },
+      },
+    );
   }
 }
 
@@ -794,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/AccessExpression.test.tsx

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import "../../testing/extend-expect.js";
+import {
+  BasePartProps,
+  createAccessExpression,
+} from "../components/AccessExpression.jsx";
+import { code } from "../index.js";
+import { printTree, renderTree } from "../render.js";
+import { Children } from "../runtime/component.js";
+
+interface TestPartProps extends BasePartProps {
+  name?: string;
+  args?: Children;
+}
+
+interface TestPart extends Record<string, unknown> {
+  name: string | undefined;
+  args: Children | undefined;
+  isFirst: boolean;
+}
+
+const { Expression, Part } = createAccessExpression<TestPartProps, TestPart>({
+  createDescriptor(props, symbol, first) {
+    return {
+      name: symbol?.name ?? props.name,
+      args: props.args,
+      isFirst: first,
+    };
+  },
+
+  getBase(part) {
+    return part.name ?? "";
+  },
+
+  formatPart(part, _prevPart, _inCallChain) {
+    if (part.args !== undefined) {
+      return code`.${part.name}(${part.args})`;
+    }
+    return code`.${part.name}`;
+  },
+
+  isCallPart(part) {
+    return part.args !== undefined;
+  },
+});
+
+describe("createAccessExpression", () => {
+  it("renders a single part as the base", () => {
+    expect(
+      <Expression>
+        <Part name="foo" />
+      </Expression>,
+    ).toRenderTo("foo");
+  });
+
+  it("renders multiple parts with dot access", () => {
+    expect(
+      <Expression>
+        <Part name="foo" />
+        <Part name="bar" />
+        <Part name="baz" />
+      </Expression>,
+    ).toRenderTo("foo.bar.baz");
+  });
+
+  it("renders parts with call arguments", () => {
+    expect(
+      <Expression>
+        <Part name="foo" />
+        <Part name="bar" args="x, y" />
+      </Expression>,
+    ).toRenderTo("foo.bar(x, y)");
+  });
+
+  it("returns empty for no parts", () => {
+    expect(<Expression>{false}</Expression>).toRenderTo("");
+  });
+
+  it("flattens nested Expression instances", () => {
+    const inner = (
+      <Expression>
+        <Part name="bar" />
+        <Part name="baz" />
+      </Expression>
+    );
+
+    expect(
+      <Expression>
+        <Part name="foo" />
+        {inner}
+      </Expression>,
+    ).toRenderTo("foo.bar.baz");
+  });
+
+  it("ignores non-Part children", () => {
+    expect(
+      <Expression>
+        <Part name="foo" />
+        {"some string"}
+        <Part name="bar" />
+      </Expression>,
+    ).toRenderTo("foo.bar");
+  });
+});
+
+describe("createAccessExpression: call chain formatting", () => {
+  it("uses linear format with only one call", () => {
+    const tree = renderTree(
+      <Expression>
+        <Part name="foo" />
+        <Part name="bar" args="x" />
+      </Expression>,
+    );
+    // Single call → linear, no grouping.
+    expect(printTree(tree)).toBe("foo.bar(x)");
+  });
+
+  it("uses call chain format with multiple calls", () => {
+    const tree = renderTree(
+      <Expression>
+        <Part name="foo" />
+        <Part name="bar" args="x" />
+        <Part name="baz" args="y" />
+      </Expression>,
+    );
+    // Multiple calls → call chain with group/indent wrapping.
+    const result = printTree(tree);
+    // Should contain both calls.
+    expect(result).toContain("bar(x)");
+    expect(result).toContain("baz(y)");
+  });
+});