@alloy-js/core 0.23.0-dev.8 → 0.23.0

package/docs/api/types/SourceLocation.md

@@ -0,0 +1,9 @@
+# SourceLocation
+
+## Members
+
+|              |        |   |
+| ------------ | ------ | - |
+| columnNumber | number |   |
+| fileName     | string |   |
+| lineNumber   | number |   |

package/docs/api/types/SplitProps.md

@@ -0,0 +1,12 @@
+# SplitProps
+
+```ts
+type SplitProps<T, K extends (readonly (keyof T)[])[]> = [
+    ...{
+        [P in keyof K]: P extends `${number}` ? Pick<T, Extract<K[P], readonly (keyof T)[]>[number]> : never;
+    },
+    {
+        [P in keyof T as Exclude<P, K[number][number]>]: T[P];
+    }
+];
+```

package/docs/api/types/StcComponentCreator.md

@@ -0,0 +1,9 @@
+# StcComponentCreator
+
+```ts
+type StcComponentCreator<T> = ComponentCreator<T> & {
+    code(template: TemplateStringsArray, ...substitutions: Children[]): ComponentCreator<T>;
+    text(template: TemplateStringsArray, ...substitutions: Children[]): ComponentCreator<T>;
+    children(...children: Children[]): ComponentCreator<T>;
+};
+```

package/docs/api/types/StcSignature.md

@@ -0,0 +1,5 @@
+# StcSignature
+
+```ts
+type StcSignature<T extends {}> = (...args: unknown extends T ? [] : {} extends Omit<T, "children"> ? [props?: MakeChildrenOptional<T>] : [props: MakeChildrenOptional<T>]) => StcComponentCreator<T>;
+```

package/docs/api/types/StiComponentCreator.md

@@ -0,0 +1,9 @@
+# StiComponentCreator
+
+```ts
+type StiComponentCreator<T extends keyof IntrinsicElements> = (() => IntrinsicElementBase<T>) & {
+    code(template: TemplateStringsArray, ...substitutions: Children[]): () => IntrinsicElementBase<T>;
+    text(template: TemplateStringsArray, ...substitutions: Children[]): () => IntrinsicElementBase<T>;
+    children(...children: Children[]): () => IntrinsicElementBase<T>;
+};
+```

package/docs/api/types/StiSignature.md

@@ -0,0 +1,7 @@
+# StiSignature
+
+```ts
+type StiSignature<T extends keyof IntrinsicElements> = (...args: unknown extends T ? [] : {} extends Omit<IntrinsicElements[T], "children"> ? [
+    props?: IntrinsicElements[T]
+] : [props: IntrinsicElements[T]]) => StiComponentCreator<T>;
+```

package/docs/api/types/SymbolCreator.md

@@ -0,0 +1,15 @@
+# SymbolCreator
+
+An object that can register symbols into a binder. Pass instances to the `externals` prop of `<Output>` to make library symbols resolvable.
+
+## Members
+
+|                        |                          |   |
+| ---------------------- | ------------------------ | - |
+| \[createSymbolsSymbol] | (binder: Binder) => void |   |
+
+## Remarks
+
+[`SymbolCreator`](SymbolCreator.md) 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 [TO\_SYMBOL](../../variables/to_symbol/) and [REFKEYABLE](../../variables/refkeyable/).

package/docs/api/types/SymbolRefkey.md

@@ -0,0 +1,9 @@
+# SymbolRefkey
+
+## Members
+
+Extends [RefkeyableObject](../refkeyableobject/)
+
+|     |        |   |
+| --- | ------ | - |
+| key | string |   |

package/docs/api/types/SymbolSlot.md

@@ -0,0 +1,12 @@
+# SymbolSlot
+
+## Members
+
+Extends [Component](../../../typescript/components/ensuretyperefcontext/)<{}>
+
+|               |                                                                            |                                                                                                                                          |
+| ------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| copyMembersTo | (baseSymbol: OutputSymbol) => void                                         | Copy any members from taken symbols to the given symbol.                                                                                 |
+| firstSymbol   | Ref<[OutputSymbol](../outputsymbol/) \| undefined>                         | A ref for the first symbol taken by this slot. Undefined when the Slot component has not been rendered yet or has not taken any symbols. |
+| moveMembersTo | (baseSymbol: OutputSymbol) => void                                         | Move any members from transient taken symbols to the given symbol.                                                                       |
+| ref           | Ref\<ShallowReactive\<Set<[OutputSymbol](../outputsymbol/)>> \| undefined> | A ref for the set of symbols taken by this slot. Undefined when the Slot component has not been rendered yet.                            |

package/docs/api/types/SymbolTable.md

@@ -0,0 +1,15 @@
+# SymbolTable
+
+## Members
+
+Extends [ReactiveUnionSet](../reactiveunionset/)<[OutputSymbol](../outputsymbol/)>
+
+|                 |                                                                                                    |                                                            |
+| --------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| constructor     | (key: string, binder: Binder, options: { nameConflictResolver?: NameConflictResolver; })           | Constructs a new instance of the [`SymbolTable`](SymbolTable.md) class       |
+| binder          | [Binder](../binder/) \| undefined                                                                  |                                                            |
+| copyTo          | (target: SymbolTable, options: { createRefkeys?(sourceSymbol: OutputSymbol): Refkey\[]; }) => void |                                                            |
+| key             | string                                                                                             | The key of this symbol table, e.g. “static” or “instance”. |
+| moveTo          | (target: SymbolTable) => void                                                                      |                                                            |
+| symbolNames     | ReadonlyMap\<string, [OutputSymbol](../outputsymbol/)>                                             |                                                            |
+| symbolsByRefkey | ReadonlyMap<[Refkey](../refkey/), [OutputSymbol](../outputsymbol/)>                                | The symbols defined within this scope, indexed by refkey.  |

package/docs/api/types/TakeSymbolCallback.md

@@ -0,0 +1,7 @@
+# TakeSymbolCallback
+
+## Members
+
+|                |                                |   |
+| -------------- | ------------------------------ | - |
+| Call signature | (symbol: OutputSymbol) => void |   |

package/docs/api/types/TakeSymbolsCallback.md

@@ -0,0 +1,7 @@
+# TakeSymbolsCallback
+
+## Members
+
+|                |                                       |   |
+| -------------- | ------------------------------------- | - |
+| Call signature | (symbols: Set\<OutputSymbol>) => void |   |

package/docs/api/types/Tap.md

@@ -0,0 +1,11 @@
+# Tap
+
+The return value of [createTap](../../functions/createtap/), this holds a reference to the tapped value. It will be undefined until the tapped value is initialized.
+
+## Members
+
+Extends [ComponentDefinition](../componentdefinition/)
+
+|     |                             |                          |
+| --- | --------------------------- | ------------------------ |
+| ref | ShallowRef\<T \| undefined> | Ref for the tapped value |

package/docs/api/types/TapHandler.md

@@ -0,0 +1,9 @@
+# TapHandler
+
+A function that is called when the tapped value is available.
+
+## Members
+
+|                |                    |   |
+| -------------- | ------------------ | - |
+| Call signature | (value: T) => void |   |

package/docs/api/types/Tapper.md

@@ -0,0 +1,9 @@
+# Tapper
+
+A function called when the Tap is rendered.
+
+## Members
+
+|                |                      |   |
+| -------------- | -------------------- | - |
+| Call signature | () => T \| undefined |   |

package/docs/api/types/TemplateVariableProps.md

@@ -0,0 +1,5 @@
+# TemplateVariableProps
+
+```ts
+type TemplateVariableProps = TemplateVariablePropsWithChildren | TemplateVariablePropsWithValue;
+```

package/docs/api/types/index.md

@@ -0,0 +1,122 @@
+# core — types
+
+- [AlignIntrinsicElement](AlignIntrinsicElement.md) — type AlignIntrinsicElement = IntrinsicElementBase<"align">;
+- [AppendRegionProps](AppendRegionProps.md) — type AppendRegionProps = AppendRegionPropsWithChildren | AppendRegionPropsWithContent | AppendRegionPropsBase;
+- [BaseListProps](BaseListProps.md) — <group>
+- [BasePartProps](BasePartProps.md) — Base props that all language-specific Part components must include.
+- [BasicScope](BasicScope.md) — BasicScope is a kind of OutputScope that has a single declaration space named `symbols`.
+- [BasicSymbol](BasicSymbol.md) — BasicSymbol is a kind of OutputSymbol that has instance and static members.
+- [Binder](Binder.md) — The binder tracks all output scopes and symbols.
+- [BinderOptions](BinderOptions.md)
+- [BreakParentIntrinsicElement](BreakParentIntrinsicElement.md) — type BreakParentIntrinsicElement = IntrinsicElementBase<"breakParent">;
+- [BrIntrinsicElement](BrIntrinsicElement.md) — type BrIntrinsicElement = IntrinsicElementBase<"br">;
+- [Child](Child.md) — type Child = RenderableObject | RefkeyableObject | string | boolean | number | undefined | null | void | (() => Children
+- [Children](Children.md) — type Children = Child | Children[];
+- [ChildrenOptions](ChildrenOptions.md)
+- [CommonFormatOptions](CommonFormatOptions.md) — Extends [PrintTreeOptions](../printtreeoptions/)
+- [Component](Component.md)
+- [ComponentContext](ComponentContext.md)
+- [ComponentCreator](ComponentCreator.md)
+- [ComponentDefinition](ComponentDefinition.md)
+- [ContentOutputFile](ContentOutputFile.md) — Extends [OutputFileBase](../outputfilebase/)
+- [ContentSlot](ContentSlot.md)
+- [Context](Context.md)
+- [ContextProviderProps](ContextProviderProps.md)
+- [CopyFileContext](CopyFileContext.md)
+- [CopyOutputFile](CopyOutputFile.md) — Extends [OutputFileBase](../outputfilebase/)
+- [CustomContext](CustomContext.md) — Create a custom reactive context for the children returned by the provided context.
+- [CustomContextChildrenCallback](CustomContextChildrenCallback.md) — type CustomContextChildrenCallback = (child: Children) => void;
+- [DeclarationProps](DeclarationProps.md) — type DeclarationProps = DeclarationPropsWithSymbol | DeclarationPropsWithInfo;
+- [DedentIntrinsicElement](DedentIntrinsicElement.md) — type DedentIntrinsicElement = IntrinsicElementBase<"dedent">;
+- [DedentToRootIntrinsicElement](DedentToRootIntrinsicElement.md) — type DedentToRootIntrinsicElement = IntrinsicElementBase<"dedentToRoot">;
+- [Diagnostic](Diagnostic.md)
+- [DiagnosticHandle](DiagnosticHandle.md)
+- [DiagnosticInput](DiagnosticInput.md)
+- [DiagnosticsCollector](DiagnosticsCollector.md)
+- [DiagnosticSeverity](DiagnosticSeverity.md) — type DiagnosticSeverity = "info" | "warning" | "error";
+- [DiagnosticStackEntry](DiagnosticStackEntry.md)
+- [Disposable_2](Disposable_2.md)
+- [EffectDebugOptions](EffectDebugOptions.md)
+- [EffectOptions](EffectOptions.md)
+- [ElementCache](ElementCache.md) — type ElementCache = Map<ElementCacheKey, RenderedTextTree>;
+- [ElementCacheKey](ElementCacheKey.md) — type ElementCacheKey = ComponentCreator | (() => unknown) | CustomContext;
+- [FillIntrinsicElement](FillIntrinsicElement.md) — type FillIntrinsicElement = IntrinsicElementBase<"fill">;
+- [ForCallbackArgs](ForCallbackArgs.md) — type ForCallbackArgs<T> = number extends keyof T ?
+- [ForSupportedCollections](ForSupportedCollections.md) — type ForSupportedCollections = readonly unknown[] | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | IterableItera
+- [GroupIntrinsicElement](GroupIntrinsicElement.md) — type GroupIntrinsicElement = IntrinsicElementBase<"group">;
+- [HardlineIntrinsicElement](HardlineIntrinsicElement.md) — type HardlineIntrinsicElement = IntrinsicElementBase<"hardline">;
+- [HbrIntrinsicElement](HbrIntrinsicElement.md) — type HbrIntrinsicElement = IntrinsicElementBase<"hbr">;
+- [IfBreakIntrinsicElement](IfBreakIntrinsicElement.md) — type IfBreakIntrinsicElement = IntrinsicElementBase<"ifBreak">;
+- [IndentIfBreakIntrinsicElement](IndentIfBreakIntrinsicElement.md) — type IndentIfBreakIntrinsicElement = IntrinsicElementBase<"indentIfBreak">;
+- [IndentIntrinsicElement](IndentIntrinsicElement.md) — type IndentIntrinsicElement = IntrinsicElementBase<"indent">;
+- [IntrinsicElement](IntrinsicElement.md) — type IntrinsicElement = IndentIntrinsicElement | IndentIfBreakIntrinsicElement | BrIntrinsicElement | LineIntrinsicEleme
+- [IntrinsicElementBase](IntrinsicElementBase.md)
+- [IntrinsicElements](IntrinsicElements.md)
+- [JoinOptions](JoinOptions.md)
+- [LbrIntrinsicElement](LbrIntrinsicElement.md) — type LbrIntrinsicElement = IntrinsicElementBase<"lbr">;
+- [LibrarySymbolReference](LibrarySymbolReference.md) — An object that acts as a lazy reference to an external library symbol.
+- [LineIntrinsicElement](LineIntrinsicElement.md) — type LineIntrinsicElement = IntrinsicElementBase<"line">;
+- [LineSuffixBoundaryIntrinsicElement](LineSuffixBoundaryIntrinsicElement.md) — type LineSuffixBoundaryIntrinsicElement = IntrinsicElementBase<"lineSuffixBoundary">;
+- [LineSuffixIntrinsicElement](LineSuffixIntrinsicElement.md) — type LineSuffixIntrinsicElement = IntrinsicElementBase<"lineSuffix">;
+- [LiterallineIntrinsicElement](LiterallineIntrinsicElement.md) — type LiterallineIntrinsicElement = IntrinsicElementBase<"literalline">;
+- [MakeChildrenOptional](MakeChildrenOptional.md) — type MakeChildrenOptional<T extends object> = T extends {
+- [MarkAsRootIntrinsicElement](MarkAsRootIntrinsicElement.md) — type MarkAsRootIntrinsicElement = IntrinsicElementBase<"markAsRoot">;
+- [MatchProps](MatchProps.md)
+- [MemberDeclarationProps](MemberDeclarationProps.md) — type MemberDeclarationProps = MemberDeclarationPropsWithInfo | MemberDeclarationPropsWithSymbol;
+- [MemberDescriptor](MemberDescriptor.md) — Describes a member in a member access chain, tracking both the symbol and whether this specific member was accessed via
+- [MemberRefkey](MemberRefkey.md) — Extends [RefkeyableObject](../refkeyableobject/)
+- [MemberResolutionContext](MemberResolutionContext.md) — The context for a member resolution.
+- [MemberResolver](MemberResolver.md) — A callback that performs access-control filtering during member resolution.
+- [MemberScopeProps](MemberScopeProps.md) — type MemberScopeProps = MemberScopePropsWithValue | MemberScopePropsWithInfo;
+- [Metadata](Metadata.md) — type Metadata = object;
+- [NameConflictResolver](NameConflictResolver.md) — A callable interface invoked by the binder when two or more symbols in the same scope share a name.
+- [Namekey](Namekey.md) — Extends [SymbolRefkey](../symbolrefkey/)
+- [NamekeyOptions](NamekeyOptions.md)
+- [NamePolicy](NamePolicy.md)
+- [NamePolicyGetter](NamePolicyGetter.md) — A function that transforms a name according to a naming policy for a specific element kind.
+- [OnReactiveSetAddCallback](OnReactiveSetAddCallback.md) — type OnReactiveSetAddCallback<T> = (value: T) => T;
+- [OnReactiveSetDeleteCallback](OnReactiveSetDeleteCallback.md) — type OnReactiveSetDeleteCallback<T> = (value: T) => void;
+- [OutputDeclarationSpace](OutputDeclarationSpace.md) — A symbol table attached to an [OutputScope](../outputscope/).
+- [OutputDirectory](OutputDirectory.md) — Turning components into source text involves three different trees produced sequentially:
+- [OutputFile](OutputFile.md) — type OutputFile = ContentOutputFile | CopyOutputFile;
+- [OutputFileBase](OutputFileBase.md)
+- [OutputMemberSpace](OutputMemberSpace.md) — A symbol table attached to an [OutputSymbol](../outputsymbol/).
+- [OutputScope](OutputScope.md) — A container of symbols accessible within some scope in your output code.
+- [OutputScopeOptions](OutputScopeOptions.md)
+- [OutputSpace](OutputSpace.md) — A symbol table that belongs to either a scope (declaration space) or a symbol (member space).
+- [OutputSymbol](OutputSymbol.md) — An output symbol is a named entity that can be referenced in your output code.
+- [OutputSymbolOptions](OutputSymbolOptions.md)
+- [OutputVisitor](OutputVisitor.md) — A visitor to collect the output from [render](../../functions/render/).
+- [PrintHook](PrintHook.md)
+- [PrintTreeOptions](PrintTreeOptions.md)
+- [Props](Props.md) — type Props = Record<string, any>;
+- [ReactiveUnionSet](ReactiveUnionSet.md) — Extends Set\<T>
+- [ReactiveUnionSetOptions](ReactiveUnionSetOptions.md)
+- [Refkey](Refkey.md) — type Refkey = SymbolRefkey | MemberRefkey | Namekey;
+- [Refkeyable](Refkeyable.md) — type Refkeyable = RefkeyableObject | Refkey;
+- [RefkeyableObject](RefkeyableObject.md) — type RefkeyableObject = {
+- [RenderableObject](RenderableObject.md) — A renderable object is any object that has an `[ay.RENDERABLE]` method that returns children.
+- [RenderedTextTree](RenderedTextTree.md) — type RenderedTextTree = (string | RenderedTextTree | PrintHook)[];
+- [ResolutionResult](ResolutionResult.md) — A successful resolution of a refkey.
+- [ResolveDeclarationByKeyOptions](ResolveDeclarationByKeyOptions.md)
+- [Resource](Resource.md) — Represents an external resource fetched asynchronously.
+- [RootOptions](RootOptions.md)
+- [SbrIntrinsicElement](SbrIntrinsicElement.md) — type SbrIntrinsicElement = IntrinsicElementBase<"sbr">;
+- [ScopeProps](ScopeProps.md) — type ScopeProps = ScopePropsWithValue | ScopePropsWithInfo;
+- [SoftlineIntrinsicElement](SoftlineIntrinsicElement.md) — type SoftlineIntrinsicElement = IntrinsicElementBase<"softline">;
+- [SourceLocation](SourceLocation.md)
+- [SplitProps](SplitProps.md) — type SplitProps<T, K extends (readonly (keyof T)[])[]> = [
+- [StcComponentCreator](StcComponentCreator.md) — type StcComponentCreator<T> = ComponentCreator<T> & {
+- [StcSignature](StcSignature.md) — type StcSignature<T extends {}> = (...args: unknown extends T ?
+- [StiComponentCreator](StiComponentCreator.md) — type StiComponentCreator<T extends keyof IntrinsicElements> = (() => IntrinsicElementBase<T>) & {
+- [StiSignature](StiSignature.md) — type StiSignature<T extends keyof IntrinsicElements> = (...args: unknown extends T ?
+- [SymbolCreator](SymbolCreator.md) — An object that can register symbols into a binder.
+- [SymbolRefkey](SymbolRefkey.md) — Extends [RefkeyableObject](../refkeyableobject/)
+- [SymbolSlot](SymbolSlot.md) — Extends [Component](../../../typescript/components/ensuretyperefcontext/)<{}>
+- [SymbolTable](SymbolTable.md) — Extends [ReactiveUnionSet](../reactiveunionset/)<[OutputSymbol](../outputsymbol/)>
+- [TakeSymbolCallback](TakeSymbolCallback.md)
+- [TakeSymbolsCallback](TakeSymbolsCallback.md)
+- [Tap](Tap.md) — The return value of [createTap](../../functions/createtap/), this holds a reference to the tapped value.
+- [TapHandler](TapHandler.md) — A function that is called when the tapped value is available.
+- [Tapper](Tapper.md) — A function called when the Tap is rendered.
+- [TemplateVariableProps](TemplateVariableProps.md) — type TemplateVariableProps = TemplateVariablePropsWithChildren | TemplateVariablePropsWithValue;

package/docs/api/variables/FormatOptions.md

@@ -0,0 +1,5 @@
+# FormatOptions
+
+```ts
+FormatOptions: import("../index.js").ComponentDefinition<import("../context.js").ContextProviderProps<CommonFormatOptions>>
+```

package/docs/api/variables/Match.md

@@ -0,0 +1,7 @@
+# Match
+
+The Match component is used inside of a [Switch](../../components/switch/) component to define conditionally rendered blocks of content.
+
+```ts
+Match: import("../runtime/component.js").Component<MatchProps> & Required<Pick<import("../runtime/component.js").Component<MatchProps>, "tag">>
+```

package/docs/api/variables/REFKEYABLE.md

@@ -0,0 +1,5 @@
+# REFKEYABLE
+
+```ts
+REFKEYABLE: unique symbol
+```

package/docs/api/variables/RENDERABLE.md

@@ -0,0 +1,5 @@
+# RENDERABLE
+
+```ts
+RENDERABLE: unique symbol
+```

package/docs/api/variables/TO_SYMBOL.md

@@ -0,0 +1,39 @@
+# TO_SYMBOL
+
+Well-known symbol for the lazy-symbol-creation protocol used by external library descriptors. Objects implementing `[TO_SYMBOL]()` are recognized as [LibrarySymbolReference](../../types/librarysymbolreference/) values that can be passed anywhere a refkey is accepted.
+
+```ts
+TO_SYMBOL: unique symbol
+```
+
+## Remarks
+
+Implement `[TO_SYMBOL]()` on a descriptor object to register it as a referenceable library symbol. Inside the method:
+
+1. Call [Binder context accessor](../../contexts/binder-context/) to get the current binder context.
+2. Look up (or create) the symbol for that binder in a `WeakMap<object, OutputSymbol>` (use a sentinel object for the no-binder case, since `WeakMap` keys must be objects).
+3. On first creation, construct the symbol and register it into the appropriate space for your library, passing `{ binder }` (see \[unresolved link]).
+
+The method is called by language package code each time the descriptor is used as a reference (e.g. inside `ref()`). It is NOT called by the binder itself.
+
+## Example
+
+```ts
+const defaultKey = {};
+const symbols = new WeakMap<object, MySymbol>();
+const descriptor: LibrarySymbolReference = {
+  [REFKEYABLE]() {
+    return descriptor[TO_SYMBOL]().refkeys[0];
+  },
+  [TO_SYMBOL]() {
+    const binder = useBinder();
+    const key = binder ?? defaultKey;
+    let sym = symbols.get(key);
+    if (!sym) {
+      sym = new MySymbol("SomeType", space, { binder });
+      symbols.set(key, sym);
+    }
+    return sym;
+  },
+};
+```

package/docs/api/variables/contextsByKey.md

@@ -0,0 +1,5 @@
+# contextsByKey
+
+```ts
+contextsByKey: Map<symbol, ComponentContext<any>>
+```

package/docs/api/variables/index.md

@@ -0,0 +1,11 @@
+# core — variables
+
+- [contextsByKey](contextsByKey.md) — contextsByKey: Map<symbol, ComponentContext<any>>
+- [FormatOptions](FormatOptions.md) — FormatOptions: import("../index.js").ComponentDefinition<import("../context.js").ContextProviderProps<CommonFormatOption
+- [intrinsicElementKey](intrinsicElementKey.md) — intrinsicElementKey: unique symbol
+- [Match](Match.md) — The Match component is used inside of a [Switch](../../components/switch/) component to define conditionally rendered bl
+- [matchTag](matchTag.md) — matchTag: unique symbol
+- [printHookTag](printHookTag.md) — Print hook types and utilities.
+- [REFKEYABLE](REFKEYABLE.md) — REFKEYABLE: unique symbol
+- [RENDERABLE](RENDERABLE.md) — RENDERABLE: unique symbol
+- [TO_SYMBOL](TO_SYMBOL.md) — Well-known symbol for the lazy-symbol-creation protocol used by external library descriptors.

package/docs/api/variables/intrinsicElementKey.md

@@ -0,0 +1,5 @@
+# intrinsicElementKey
+
+```ts
+intrinsicElementKey: unique symbol
+```

package/docs/api/variables/matchTag.md

@@ -0,0 +1,5 @@
+# matchTag
+
+```ts
+matchTag: unique symbol
+```

package/docs/api/variables/printHookTag.md

@@ -0,0 +1,7 @@
+# printHookTag
+
+Print hook types and utilities. This is a separate file to avoid circular dependencies between render.ts and debug/render.ts.
+
+```ts
+printHookTag: unique symbol
+```

package/docs/components.md

@@ -0,0 +1,97 @@
+# Components
+
+Alloy uses a custom JSX transform similar to Solid.js. JSX compiles to `createComponent()` calls — components run once and return reactive [Children](api/types/Children.md).
+
+## Defining Components
+
+```tsx
+import { Children } from "@alloy-js/core";
+
+interface GreetingProps {
+  name: string;
+}
+
+function Greeting(props: GreetingProps) {
+  return <>Hello, {props.name}!</>;
+}
+```
+
+> **Important:** Do not destructure props. Props are reactive getters — destructuring breaks reactivity.
+
+## Children
+
+[`Children`](api/types/Children.md) is the universal return type. It encompasses strings, numbers, `Ref` values, refkeys, arrays, [`ComponentCreator`](api/types/ComponentCreator.md)s, intrinsic elements, and objects implementing [`RENDERABLE`](api/variables/RENDERABLE.md).
+
+`children` is a reserved prop for nested JSX content:
+
+```tsx
+function Wrapper(props: { children?: Children }) {
+  return <>({props.children})</>;
+}
+```
+
+### Children Utilities
+
+- [`childrenArray(fn, options?)`](api/functions/childrenArray.md) — resolves `Children` into a flat array.
+- [`findKeyedChild(children, tag)`](api/functions/findKeyedChild.md) — finds a tagged child by its tag symbol.
+- [`findUnkeyedChildren(children)`](api/functions/findUnkeyedChildren.md) — returns all non-tagged children.
+
+### Tagged Children
+
+[`taggedComponent(tag, component)`](api/functions/taggedComponent.md) marks a component with a symbol tag, enabling structured child decomposition:
+
+```tsx
+const bodyTag = Symbol();
+const Body = taggedComponent(bodyTag, (props: { children: Children }) => {
+  return props.children;
+});
+
+function MyComponent(props: { children: Children }) {
+  const kids = childrenArray(() => props.children);
+  const body = findKeyedChild(kids, bodyTag);
+  const rest = findUnkeyedChildren(kids);
+  return (
+    <>
+      {rest}
+      {body}
+    </>
+  );
+}
+```
+
+## The RENDERABLE Protocol
+
+Any object can participate in rendering by implementing [`[RENDERABLE](): Children`](api/variables/RENDERABLE.md).
+
+## Props Utilities
+
+- [`mergeProps(...sources)`](api/functions/mergeProps.md) — reactive merge (last source wins).
+- [`splitProps(props, ...keyGroups)`](api/functions/splitProps.md) — split by key groups, preserving reactivity.
+- [`defaultProps(props, defaults)`](api/functions/defaultProps.md) — apply defaults, preserving reactive getters.
+
+## Taps
+
+Taps let a parent component access context provided by its children. [`createTap()`](api/functions/createTap.md) returns a component and a reactive ref — render the component inside the child tree, read the ref from the parent. Specialized variants:
+
+- [`createDeclarationTap()`](api/functions/createDeclarationTap.md) — taps [`DeclarationContext`](api/contexts/Declaration-context.md).
+- [`createMemberTap()`](api/functions/createMemberTap.md) — taps [`MemberDeclarationContext`](api/contexts/MemberDeclaration-context.md).
+- [`createScopeTap()`](api/functions/createScopeTap.md) — taps the current scope.
+- [`createSourceFileTap()`](api/functions/createSourceFileTap.md) — taps [`SourceFileContext`](api/contexts/SourceFile-context.md).
+
+## `stc()` — Static Template Composition
+
+[`stc(Component)`](api/functions/stc.md) wraps a component into a callable creator with `.code()`, `.text()`, and `.children()` methods. This enables fluent composition without JSX:
+
+```ts
+const M = stc(MyComponent);
+
+// These are equivalent:
+M({ name: "hello" }).code`// ...`;
+<MyComponent name="hello">// ...</MyComponent>
+```
+
+- `.code(template)` — sets children via a code template literal.
+- `.text(template)` — sets children via a text template literal.
+- `.children(...children)` — sets children directly.
+
+Language packages export stc-wrapped versions of key components from a `stc/` subpath.

package/docs/context.md

@@ -0,0 +1,67 @@
+# Context
+
+Dependency injection through the component tree via the reactive owner chain, similar to React's Context API.
+
+## Creating a Context
+
+```ts
+import { ComponentContext, createContext, useContext } from "@alloy-js/core";
+
+interface SectionContext {
+  level: number;
+}
+
+const SectionContext: ComponentContext<SectionContext> =
+  createContext<SectionContext>({ level: 1 });
+```
+
+See [`createContext`](api/functions/createContext.md), [`ComponentContext`](api/types/ComponentContext.md).
+
+The argument is the default value when no provider is found.
+
+## Providing Values
+
+```tsx
+<SectionContext.Provider value={{ level: 2 }}>
+  <MyComponent />
+</SectionContext.Provider>
+```
+
+## Consuming Values
+
+```ts
+function MyComponent() {
+  const section = useContext(SectionContext);
+}
+```
+
+[`useContext`](api/functions/useContext.md) walks the owner chain (not the JSX tree) to find the nearest provider.
+
+## Built-in Contexts
+
+| Context                                                             | Provides                              | Set by                                                                       |
+| ------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
+| [`BinderContext`](api/contexts/Binder-context.md)                   | The binder instance                   | [`<Output>`](api/components/Output.md)                                       |
+| [`ScopeContext`](api/contexts/Scope-context.md)                     | Current `OutputScope`                 | [`<Scope>`](api/components/Scope.md), [`<Output>`](api/components/Output.md) |
+| [`DeclarationContext`](api/contexts/Declaration-context.md)         | Current `OutputSymbol` being declared | [`<Declaration>`](api/components/Declaration.md)                             |
+| [`MemberContext`](api/contexts/Member-context.md)                   | Owner symbol for new members          | [`<MemberScope>`](api/components/MemberScope.md)                             |
+| [`SourceFileContext`](api/contexts/SourceFile-context.md)           | Current source file                   | [`<SourceFile>`](api/components/SourceFile.md)                               |
+| [`SourceDirectoryContext`](api/contexts/SourceDirectory-context.md) | Current source directory              | [`<SourceDirectory>`](api/components/SourceDirectory.md)                     |
+| [`NamePolicyContext`](api/contexts/NamePolicy-context.md)           | Name policy                           | [`<Output>`](api/components/Output.md)                                       |
+
+## Format Options Context
+
+[`createFormatOptionsContextFor<T>(filetype, defaults?)`](api/functions/createFormatOptionsContextFor.md) creates a provider/consumer pair for language-specific formatting options (e.g., brace style, indentation). Returns `{ Provider, useFormatOptions }`.
+
+The `Provider` accepts a value typed as `T` (not `Partial<T>`), so TypeScript requires all non-optional fields. At runtime, the Provider value is spread-merged over `defaults`, overriding each key it supplies. Use `useFormatOptions(overrides?)` for per-call partial overrides — it accepts `Partial<T>` and merges onto current effective options. Undefined override values are ignored.
+
+Merge precedence: `defaults` (lowest) → Provider `value` (full T) → `useFormatOptions(overrides?)` (highest).
+
+## Structuring Custom Contexts
+
+When defining a new context, co-locate these pieces:
+
+- **Interface** — the shape of the context value (e.g., `SourceFileContext`, `NamespaceContext`).
+- **Context variable** — created with `createContext()` or `createNamedContext()`.
+- **`use` function** — wraps `useContext()` with defaults (e.g., `useSourceFile()`, `useNamespaceContext()`).
+- **Provider component** (when needed) — e.g., format options contexts.

package/docs/control-flow.md

@@ -0,0 +1,5 @@
+# Control Flow
+
+- [**`<Show>`**](api/components/Show.md) — conditional rendering. Renders `children` when `when` is truthy, otherwise `fallback`.
+- [**`<For>`**](api/components/For.md) — iteration with joiner props (`comma`, `hardline`, etc.).
+- [**`<Switch>`**](api/components/Switch.md) / [**`<Match>`**](api/variables/Match.md) — multi-branch conditional. Use `<Match else>` for default.