@reckona/mreact-compat 0.0.159 → 0.0.161

package/src/hooks.ts

@@ -92,6 +92,7 @@ interface ExternalStoreCheck {
   value: unknown;
 }
 
+/** Cache scope that stores memoized cache() results and cancellation state. */
 export interface CacheScope {
   functionCaches: WeakMap<(...args: never[]) => unknown, CacheTrieNode>;
   controller: AbortController;
@@ -194,6 +195,7 @@ let strictMemoOwnerId = 0;
 const strictMemoObjectOwnerIds = new WeakMap<object, number>();
 const queuedTransitionRerenders = new Map<RootRuntime, TransitionContext>();
 const queuedEventRerenders = new Set<RootRuntime>();
+/** React version string matched by the compatibility layer. */
 export const version = "19.2.6";
 
 export interface ReactiveTextBinding {
@@ -204,6 +206,7 @@ export interface ReactiveTextBinding {
 const reactiveTextBindingsByNode = new WeakMap<Text, ReactiveTextBinding>();
 const hydratedIdsByRuntime = new WeakMap<RootRuntime, Map<string, string>>();
 
+/** Flushes React-compatible updates produced inside a test interaction. */
 export function act<T>(callback: () => T): T extends PromiseLike<unknown> ? Promise<void> : void {
   const previousPriority = currentEventPriority;
   currentEventPriority = "discrete";
@@ -267,6 +270,7 @@ function flushActWork(): void {
   flushEffectFlushRerenders();
 }
 
+/** Priority category used while batching an event callback. */
 export type EventPriority = "discrete" | "continuous" | "default";
 export type RenderPriority = "sync" | "transition" | "continuous";
 
@@ -406,6 +410,7 @@ export function createRootRuntime(
   };
 }
 
+/** Creates an isolated cache scope for cache() and cacheSignal(). */
 export function createCacheScope(): CacheScope {
   return {
     functionCaches: new WeakMap(),
@@ -414,12 +419,14 @@ export function createCacheScope(): CacheScope {
   };
 }
 
+/** Clears a cache scope and aborts work tied to its previous signal. */
 export function refreshCacheScope(scope: CacheScope): void {
   scope.controller.abort();
   scope.functionCaches = new WeakMap();
   scope.controller = new AbortController();
 }
 
+/** Runs a callback with a cache scope active for nested cache() calls. */
 export function runWithCacheScope<T>(scope: CacheScope, callback: () => T): T {
   const previousScope = hookRenderState.currentCacheScope;
   const previousGlobalScope = getGlobalCacheScope();
@@ -756,6 +763,7 @@ function clonePortalNodes(source: Map<Element, Set<Node>>): Map<Element, Set<Nod
   return clone;
 }
 
+/** Stores component-local state and returns the current value with an updater. */
 export function useState<T>(
   initial: T | (() => T),
 ): [T, (value: T | ((previous: T) => T)) => void] {
@@ -904,6 +912,7 @@ function isReactiveTextBinding(value: unknown): value is ReactiveTextBinding {
   );
 }
 
+/** Stores reducer-managed component state and returns the current state with a dispatch function. */
 export function useReducer<TState, TAction, TInitial = TState>(
   reducer: (state: TState, action: TAction) => TState,
   initialArg: TInitial,
@@ -940,6 +949,7 @@ export function useReducer<TState, TAction, TInitial = TState>(
   return [state, dispatchRef.current];
 }
 
+/** Returns a stable mutable ref object for the component instance. */
 export function useRef<T>(initial: T): { current: T } {
   const instance = requireInstance();
   const index = instance.hookIndex;
@@ -964,6 +974,7 @@ export function useRef<T>(initial: T): { current: T } {
   return slot.value as { current: T };
 }
 
+/** Returns a stable id string that matches server and client rendering. */
 export function useId(): string {
   const runtime = requireRuntime();
   const instance = requireInstance();
@@ -1000,6 +1011,7 @@ export function useId(): string {
   return idRef.current;
 }
 
+/** Assigns a custom imperative handle to a forwarded ref. */
 export function useImperativeHandle<T>(
   ref: unknown,
   create: () => T,
@@ -1019,6 +1031,7 @@ export function useImperativeHandle<T>(
     : { kind: "imperative-handle", deps });
 }
 
+/** Memoizes a computed value until its dependency list changes. */
 export function useMemo<T>(factory: () => T, deps?: readonly unknown[]): T {
   const runtime = requireRuntime();
   const instance = requireInstance();
@@ -1159,6 +1172,7 @@ function runWithoutDevToolsHookTracking<T>(callback: () => T): T {
   }
 }
 
+/** Memoizes a callback reference until its dependency list changes. */
 export function useCallback<T extends (...args: never[]) => unknown>(
   callback: T,
   deps?: readonly unknown[],
@@ -1170,6 +1184,7 @@ export function useCallback<T extends (...args: never[]) => unknown>(
   return value;
 }
 
+/** Records a value for React DevTools hook inspection. */
 export function useDebugValue(_value: unknown, _format?: (value: unknown) => unknown): void {
   const instance = requireInstance();
   const index = instance.hookIndex;
@@ -1199,6 +1214,7 @@ export function useDebugValue(_value: unknown, _format?: (value: unknown) => unk
   });
 }
 
+/** Creates a stable event callback that always calls the latest implementation. */
 export function useEffectEvent<TArgs extends unknown[], TResult>(
   callback: (...args: TArgs) => TResult,
 ): (...args: TArgs) => TResult {
@@ -1216,6 +1232,7 @@ export function useEffectEvent<TArgs extends unknown[], TResult>(
   return event;
 }
 
+/** Runs an effect after the rendered output has been committed. */
 export function useEffect(
   callback: EffectCallback,
   deps?: readonly unknown[],
@@ -1226,6 +1243,7 @@ export function useEffect(
     : { kind: "effect", effectKind: "normal", deps });
 }
 
+/** Runs an insertion effect before layout effects are flushed. */
 export function useInsertionEffect(
   callback: EffectCallback,
   deps?: readonly unknown[],
@@ -1236,6 +1254,7 @@ export function useInsertionEffect(
     : { kind: "effect", effectKind: "insertion", deps });
 }
 
+/** Runs a layout effect after DOM mutations and before normal effects. */
 export function useLayoutEffect(
   callback: EffectCallback,
   deps?: readonly unknown[],
@@ -1246,6 +1265,7 @@ export function useLayoutEffect(
     : { kind: "effect", effectKind: "layout", deps });
 }
 
+/** Subscribes to an external store with snapshot checks for consistent rendering. */
 export function useSyncExternalStore<T>(
   subscribe: (listener: () => void) => () => void,
   getSnapshot: () => T,
@@ -1321,6 +1341,7 @@ export function useSyncExternalStore<T>(
   return slot.value as T;
 }
 
+/** Tracks state and pending status for an action that receives the previous state. */
 export function useActionState<TState, TPayload>(
   action: (previousState: TState, payload: TPayload) => TState | Promise<TState>,
   initialState: TState,
@@ -1369,6 +1390,7 @@ export function useActionState<TState, TPayload>(
   ];
 }
 
+/** Returns an optimistic state value and dispatcher layered on top of a base state. */
 export function useOptimistic<TState, TPayload>(
   state: TState,
   update?: (state: TState, payload: TPayload) => TState,
@@ -1419,6 +1441,7 @@ export function useOptimistic<TState, TPayload>(
   return [slot.optimisticState as TState, slot.dispatch as (payload: TPayload) => void];
 }
 
+/** Reads a context-like value or suspends on a thenable until it resolves. */
 export function use<T>(usable: PromiseLike<T> | unknown): T {
   if (isReactCompatContext(usable)) {
     return useContext(usable) as T;
@@ -1431,6 +1454,7 @@ export function use<T>(usable: PromiseLike<T> | unknown): T {
   return usable as T;
 }
 
+/** Memoizes a function within the currently active cache scope. */
 export function cache<TArgs extends unknown[], TResult>(
   callback: (...args: TArgs) => TResult,
 ): (...args: TArgs) => TResult {
@@ -1464,15 +1488,18 @@ export function cache<TArgs extends unknown[], TResult>(
   };
 }
 
+/** Returns the abort signal for the currently active cache scope. */
 export function cacheSignal(): AbortSignal | null {
   return getCurrentCacheScope()?.controller.signal ?? null;
 }
 
+/** Returns the current owner stack captured for cache diagnostics. */
 export function captureOwnerStack(): string | null {
   const stack = getCurrentCacheScope()?.ownerStack ?? emptyCacheOwnerStack;
   return stack.length === 0 ? null : stack.join("\n");
 }
 
+/** Returns a callback placeholder for refreshing the current cache boundary. */
 export function unstable_useCacheRefresh(): () => void {
   return useCallback(() => undefined, []);
 }
@@ -1521,9 +1548,12 @@ function readThenable<T>(thenable: PromiseLike<T>): T {
   throw thenable;
 }
 
+/** Callback body scheduled as transition work. */
 export type TransitionScope = () => void;
+/** Function that schedules a transition scope. */
 export type StartTransition = (scope: TransitionScope) => void;
 
+/** Schedules non-urgent updates produced inside a transition scope. */
 export function startTransition(scope: TransitionScope): void {
   const context = {
     syncVersion,
@@ -1533,6 +1563,7 @@ export function startTransition(scope: TransitionScope): void {
   runTransitionScope(scope, context);
 }
 
+/** Runs a callback while updates are batched at the requested event priority. */
 export function runWithEventPriority<T>(
   priority: EventPriority,
   callback: () => T,
@@ -1583,6 +1614,7 @@ export function runWithHostCommit<T>(callback: () => T): T {
   }
 }
 
+/** Returns transition pending state and a function that starts transition work. */
 export function useTransition(): [boolean, StartTransition] {
   const instance = requireInstance();
   const [pending, setPending] = runWithoutDevToolsHookTracking(() => useState(false));
@@ -1623,6 +1655,7 @@ export function useTransition(): [boolean, StartTransition] {
   ];
 }
 
+/** Defers a value update so urgent renders can commit first. */
 export function useDeferredValue<T>(value: T, initialValue?: T): T {
   const [deferredValue, setDeferredValue] = runWithoutDevToolsHookTracking(() =>
     useState(arguments.length > 1 ? (initialValue as T) : value)
@@ -1929,24 +1962,10 @@ function runActionStateDispatch(
   );
 }
 
-function scheduleInstanceUpdate(
+export function scheduleRuntimeRerender(
   runtime: RootRuntime,
-  instance: ComponentInstance,
   options: { deferSync?: boolean } = {},
 ): void {
-  if (instance.disposed === true) {
-    return;
-  }
-
-  instance.dirty = true;
-  if (
-    hookRenderState.currentRuntime === runtime &&
-    hookRenderState.currentInstance === instance
-  ) {
-    runtime.renderPhaseUpdate = true;
-    return;
-  }
-
   if (transitionDepth === 0) {
     syncVersion += 1;
     if (hookRenderState.hostCommitDepth > 0) {
@@ -1974,6 +1993,27 @@ function scheduleInstanceUpdate(
   }
 }
 
+function scheduleInstanceUpdate(
+  runtime: RootRuntime,
+  instance: ComponentInstance,
+  options: { deferSync?: boolean } = {},
+): void {
+  if (instance.disposed === true) {
+    return;
+  }
+
+  instance.dirty = true;
+  if (
+    hookRenderState.currentRuntime === runtime &&
+    hookRenderState.currentInstance === instance
+  ) {
+    runtime.renderPhaseUpdate = true;
+    return;
+  }
+
+  scheduleRuntimeRerender(runtime, options);
+}
+
 function flushHostCommitRerenders(): void {
   if (
     hookRenderState.hostCommitDepth > 0 ||

package/src/host-reconciler.ts

@@ -1207,7 +1207,7 @@ function createHostFiberImpl(
       areMemoPropsEqual(memoType, previousMemoState.props, node.props)
     ) {
       markActiveInstanceKeys(runtime, previousMemoState.instanceKeys);
-      fiber.child = current?.child;
+      fiber.child = getSkippedChild(current);
       fiber.memoizedState = previousMemoState;
       return { fiber, consumed: options.previousNodes?.length ?? 0 };
     }
@@ -1317,6 +1317,8 @@ function createHostFiberImpl(
       current?.tag === "class-component" && current.type === classType
         ? (current.stateNode as ClassComponentInstance)
         : undefined;
+    const hasCurrentClassFiber =
+      current?.tag === "class-component" && current.type === classType;
     const rendered = renderClassComponentWithRuntime(
       classType,
       node.props,
@@ -1331,12 +1333,13 @@ function createHostFiberImpl(
           previousClassChildKeys,
           `${path}.class`,
         ),
+        allowSkip: hasCurrentClassFiber,
       },
     );
     applyRef(node.ref, rendered.kind === "skip" ? current?.stateNode : rendered.instance);
 
     if (rendered.kind === "skip") {
-      fiber.child = current?.child;
+      fiber.child = getSkippedChild(current);
       return { fiber, consumed: options.previousNodes?.length ?? 0 };
     }
 
@@ -1414,7 +1417,7 @@ function createHostFiberImpl(
       !hasPendingAsyncChild(current?.child)
     ) {
       markActiveInstanceKeys(runtime, previousFunctionState.instanceKeys);
-      fiber.child = current?.child;
+      fiber.child = getSkippedChild(current);
       fiber.memoizedState = current?.memoizedState;
       fiber.stateNode = previousFunctionState;
       return { fiber, consumed: options.previousNodes?.length ?? 0 };
@@ -1651,6 +1654,18 @@ function commitHostDirtyFiber(
     if (directTextChild !== undefined) {
       const text = syncDirectHostTextChild(element, directTextChild);
       subscribeReactiveHostTextBinding(props, text);
+    } else if (
+      fiber.hostChildListChanged ||
+      fiber.childListChanged ||
+      fiber.subtreeChildListChanged
+    ) {
+      const childNodes = commitHostChildren(fiber.child, element, eventRoot, `${path}.c`, options);
+      if (
+        !(childNodes.length === 0 && committedPortalContainers.has(element)) &&
+        !shouldPreserveContentEditableChildren(element, props, childNodes)
+      ) {
+        syncChildNodes(element, childNodes);
+      }
     } else if (fiber.subtreeFlags !== NoFlags) {
       commitHostDirtyChildren(fiber.child, element, eventRoot, `${path}.c`, options);
     }
@@ -1793,7 +1808,7 @@ function commitHostAppendSuffix(
   path: string,
   options: RenderOptions,
 ): boolean {
-  const append = getPlacementAppendSuffix(fiber.child) ?? getAppendSuffix(fiber.alternate?.child, fiber.child);
+  const append = getAppendSuffix(fiber.alternate?.child, fiber.child);
 
   if (append === undefined) {
     return false;
@@ -1813,39 +1828,6 @@ function commitHostAppendSuffix(
   return true;
 }
 
-function getPlacementAppendSuffix(next: Fiber | undefined): { fiber: Fiber; index: number } | undefined {
-  let nextCursor = next;
-  let index = 0;
-
-  while (nextCursor !== undefined) {
-    if ((nextCursor.flags & Placement) !== NoFlags) {
-      if (index === 0) {
-        return undefined;
-      }
-
-      let appendCursor: Fiber | undefined = nextCursor;
-
-      while (appendCursor !== undefined) {
-        if ((appendCursor.flags & Placement) === NoFlags) {
-          return undefined;
-        }
-        appendCursor = appendCursor.sibling;
-      }
-
-      return { fiber: nextCursor, index };
-    }
-
-    if (hasHostCommitWork(nextCursor)) {
-      return undefined;
-    }
-
-    nextCursor = nextCursor.sibling;
-    index += 1;
-  }
-
-  return undefined;
-}
-
 function commitHostSingleRemoval(fiber: Fiber, parent: ParentNode): boolean {
   const removed = getSingleRemovedFiber(fiber.alternate?.child, fiber.child);
 
@@ -1959,6 +1941,22 @@ function collectCommittedHostNodes(fiber: Fiber): Node[] {
   return nodes;
 }
 
+function getSkippedChild(current: Fiber | undefined): Fiber | undefined {
+  const child = current?.child;
+  const alternateChild = current?.alternate?.child;
+
+  if (
+    child !== undefined &&
+    alternateChild !== undefined &&
+    collectCommittedHostNodes(child).length === 0 &&
+    collectCommittedHostNodes(alternateChild).length > 0
+  ) {
+    return alternateChild;
+  }
+
+  return child;
+}
+
 function finishHostPassthroughFiber(fiber: Fiber): void {
   fiber.memoizedProps = fiber.pendingProps;
   finishCommittedFiber(fiber);
@@ -2000,7 +1998,9 @@ function commitHostFiber(
       fiber.hydrateExisting !== true &&
       fiber.flags === NoFlags &&
       fiber.subtreeFlags === NoFlags &&
-      fiber.hostChildListChanged !== true
+      fiber.hostChildListChanged !== true &&
+      fiber.childListChanged !== true &&
+      fiber.subtreeChildListChanged !== true
     ) {
       fiber.memoizedProps = fiber.pendingProps;
       return [element];
@@ -2045,6 +2045,7 @@ function commitHostFiber(
     } else if (
       fiber.hostChildListChanged ||
       fiber.childListChanged ||
+      fiber.subtreeChildListChanged ||
       fiber.hydrateExisting === true ||
       (fiber.subtreeFlags & Placement) !== NoFlags
     ) {

package/src/hydration.ts

@@ -1,5 +1,6 @@
 import type { ReactCompatNode } from "./element.js";
 
+/** Details passed to recoverable hydration error callbacks. */
 export interface HydrationRecoverableErrorInfo {
   kind: "tag" | "text" | "attribute" | "node" | "suspense-server-error";
   path: string;
@@ -27,6 +28,7 @@ export interface HydrationScope {
   after: ChildNode | null;
 }
 
+/** Applies streamed out-of-order hydration fragments to their placeholders. */
 export function applyStreamingHydrationFragments(
   root: ParentNode = document,
 ): void {

package/src/index.ts

@@ -20,12 +20,14 @@ export {
   lazy,
   memo,
 } from "./element.js";
+/** Element and node types exported by the React-compatible root entrypoint. */
 export type {
   ErrorBoundaryOptions,
   ElementType,
   ReactCompatElement,
   ReactCompatNode,
 } from "./element.js";
+/** DOM and form event types exported by the JSX runtime. */
 export type {
   FormEvent,
   FormEventHandler,
@@ -93,4 +95,5 @@ export {
 } from "./hooks.js";
 export { renderChildToString, renderToString } from "./server-render.js";
 export type { StartTransition, TransitionScope } from "./hooks.js";
+/** Default React-compatible namespace export. */
 export { default } from "./react-default.js";

package/src/internal.ts

@@ -1,3 +1,4 @@
+/** Internal cache-scope and event-priority helpers used by compat integrations. */
 export {
   createCacheScope,
   refreshCacheScope,

package/src/jsx-dev-runtime.ts

@@ -13,8 +13,11 @@ import type {
   JSXIntrinsicElements,
 } from "./jsx-runtime.js";
 
+/** Fragment marker used by the development JSX runtime. */
 export { Fragment };
+/** Metadata key used by compiled JSX for reactive text bindings. */
 export { REACTIVE_TEXT_BINDING_META };
+/** JSX event and attribute types re-exported by the development JSX runtime. */
 export type {
   FormEvent,
   FormEventHandler,
@@ -25,6 +28,7 @@ export type {
   JSXIntrinsicElements,
 } from "./jsx-runtime.js";
 
+/** JSX namespace exported by the development JSX runtime. */
 export namespace JSX {
   export interface Element extends ReactCompatElement {}
 
@@ -33,6 +37,7 @@ export namespace JSX {
   export interface IntrinsicElements extends JSXIntrinsicElements {}
 }
 
+/** Creates a JSX element with development metadata arguments. */
 export function jsxDEV<P extends Record<string, unknown>>(
   type: ElementType<P>,
   props: (P & { children?: ReactCompatNode; key?: unknown; ref?: unknown }) | null,

package/src/jsx-runtime.ts

@@ -9,9 +9,12 @@ import type {
   ReactCompatNode,
 } from "./element.js";
 
+/** Fragment marker used by the automatic JSX runtime. */
 export { Fragment };
+/** Metadata key used by compiled JSX for reactive text bindings. */
 export { REACTIVE_TEXT_BINDING_META };
 
+/** DOM event type with a narrowed currentTarget. */
 export type JSXEvent<
   TCurrentTarget extends EventTarget,
   TEvent extends Event = Event,
@@ -19,19 +22,23 @@ export type JSXEvent<
   readonly currentTarget: TCurrentTarget;
 };
 
+/** Event handler type used by JSX DOM attributes. */
 export type JSXEventHandler<
   TCurrentTarget extends EventTarget,
   TEvent extends Event = Event,
 > = (event: JSXEvent<TCurrentTarget, TEvent>) => unknown;
 
+/** Submit event type used by form-related JSX attributes. */
 export type FormEvent<TCurrentTarget extends EventTarget = Element> = JSXEvent<
   TCurrentTarget,
   SubmitEvent
 >;
 
+/** Submit event handler type used by form-related JSX attributes. */
 export type FormEventHandler<TCurrentTarget extends EventTarget = Element> =
   JSXEventHandler<TCurrentTarget, SubmitEvent>;
 
+/** DOM event attributes accepted by JSX elements. */
 export interface JSXDOMAttributes<TElement extends EventTarget> {
   children?: ReactCompatNode;
   onClick?: JSXEventHandler<TElement, MouseEvent>;
@@ -40,16 +47,19 @@ export interface JSXDOMAttributes<TElement extends EventTarget> {
   onSubmit?: JSXEventHandler<TElement, SubmitEvent>;
 }
 
+/** HTML attributes accepted by JSX host elements. */
 export interface JSXHTMLAttributes<TElement extends HTMLElement>
   extends JSXDOMAttributes<TElement> {
   [attributeName: string]: unknown;
 }
 
+/** Attributes accepted by every JSX element. */
 export interface JSXIntrinsicAttributes {
   key?: unknown;
   ref?: unknown;
 }
 
+/** Built-in JSX element names and their attribute types. */
 export interface JSXIntrinsicElements {
   form: JSXHTMLAttributes<HTMLFormElement> & {
     onSubmit?: JSXEventHandler<HTMLFormElement, SubmitEvent>;
@@ -67,6 +77,7 @@ export interface JSXIntrinsicElements {
   [elementName: string]: Record<string, unknown>;
 }
 
+/** JSX namespace exported by the automatic JSX runtime. */
 export namespace JSX {
   export interface Element extends ReactCompatElement {}
 
@@ -83,6 +94,7 @@ declare global {
   }
 }
 
+/** Creates a single-child JSX element for the automatic JSX runtime. */
 export function jsx<P extends Record<string, unknown>>(
   type: ElementType<P>,
   props: (P & { children?: ReactCompatNode; key?: unknown; ref?: unknown }) | null,
@@ -91,6 +103,7 @@ export function jsx<P extends Record<string, unknown>>(
   return createElementFromJsx(type, props, key);
 }
 
+/** Creates a multi-child JSX element for the automatic JSX runtime. */
 export function jsxs<P extends Record<string, unknown>>(
   type: ElementType<P>,
   props: (P & { children?: ReactCompatNode; key?: unknown; ref?: unknown }) | null,

package/src/react-default.ts

@@ -68,6 +68,7 @@ import {
 } from "./hooks.js";
 import { renderChildToString, renderToString } from "./server-render.js";
 
+/** Default React-compatible namespace export. */
 const ReactCompat = {
   Component,
   PureComponent,
@@ -131,4 +132,5 @@ const ReactCompat = {
   version,
 } as const;
 
+/** Default React-compatible namespace export. */
 export default ReactCompat;

package/src/root.ts

@@ -41,15 +41,18 @@ import {
 import type { Fiber, FiberRoot } from "./fiber.js";
 import { renderIntoContainer } from "./reconciler.js";
 
+/** Root controller returned by createRoot and hydrateRoot. */
 export interface Root {
   render(element: ReactCompatNode): void;
   unmount(): void;
 }
 
+/** Options used when creating a client render root. */
 export interface RootOptions {
   identifierPrefix?: string;
 }
 
+/** Options used when hydrating server-rendered markup. */
 export interface HydrateRootOptions {
   onRecoverableError?: (
     error: Error,
@@ -60,11 +63,13 @@ export interface HydrateRootOptions {
   identifierPrefix?: string;
 }
 
+/** Controller for deferred or selective streaming hydration. */
 export interface StreamingHydrationRoot {
   hydrate(element: ReactCompatNode, options?: HydrateRootOptions): Root;
   dispose(): void;
 }
 
+/** Options for creating a streaming hydration root. */
 export interface StreamingHydrationRootOptions {
   manifest?: EventHydrationManifest;
   manifestRoot?: ParentNode;
@@ -74,12 +79,14 @@ export interface StreamingHydrationRootOptions {
   selectiveHydration?: SelectiveHydrationOptions;
 }
 
+/** Rules that choose which boundary to hydrate after a captured event. */
 export interface SelectiveHydrationOptions {
   element?: ReactCompatNode;
   options?: HydrateRootOptions | ((event: Event) => HydrateRootOptions);
   boundaries?: Record<string, SelectiveHydrationBoundary>;
 }
 
+/** Element and options used to hydrate one selective boundary. */
 export interface SelectiveHydrationBoundary {
   element: ReactCompatNode;
   options?: HydrateRootOptions | ((event: Event) => HydrateRootOptions);
@@ -87,6 +94,7 @@ export interface SelectiveHydrationBoundary {
 
 const legacyRoots = new WeakMap<Element, Root>();
 
+/** Creates a root that renders React-compatible nodes into a DOM container. */
 export function createRoot(
   container: Element,
   options: RootOptions = {},
@@ -236,16 +244,19 @@ function renderHydratingHostFiberIntoContainer(
   throw new Error("Store unstable.");
 }
 
+/** Renders a React-compatible node into a legacy root container. */
 export function render(element: ReactCompatNode, container: Element): void {
   const root = legacyRoots.get(container) ?? createRoot(container);
   legacyRoots.set(container, root);
   root.render(element);
 }
 
+/** Runs updates synchronously and flushes pending reactive work before returning. */
 export function flushSync<T>(callback: () => T): T {
   return flushSyncUpdates(callback);
 }
 
+/** Hydrates server-rendered markup with a React-compatible element tree. */
 export function hydrateRoot(
   container: Element,
   element: ReactCompatNode,
@@ -355,6 +366,7 @@ function laneForRenderPriority(priority: RenderPriority): Lane {
   return SyncLane;
 }
 
+/** Creates a root that can hydrate streamed or selectively revealed markup. */
 export function createStreamingHydrationRoot(
   container: Element,
   options: StreamingHydrationRootOptions = {},
@@ -434,6 +446,7 @@ export function createStreamingHydrationRoot(
   };
 }
 
+/** Unmounts a legacy root from a container and reports whether anything was removed. */
 export function unmountComponentAtNode(container: Element): boolean {
   const root = legacyRoots.get(container);