@gtkx/react 0.20.0 → 1.0.0-rc.1

package/src/reconciler/host-config.ts

@@ -0,0 +1,405 @@
+import * as GObject from "@gtkx/gi/gobject";
+import * as Gtk from "@gtkx/gi/gtk";
+import { type Context, createContext } from "react";
+import type ReactReconciler from "react-reconciler";
+import { DiscreteEventPriority } from "react-reconciler/constants.js";
+import { typeChainIncludes } from "../utils/gtype.js";
+import { applyAccessibleProps, isAccessibleProp } from "./accessible.js";
+import { applyProps } from "./apply-props.js";
+import { runCommitFlush } from "./commit-flush.js";
+import { attachNode, detachFromParent, detachNode, resyncWrapperNode } from "./dispatch.js";
+import { applyElementProps, reapplyLazyProps } from "./element-prop-appliers.js";
+import { isAppliedProp } from "./element-props.js";
+import { createElementInstance, createWrapperInstance } from "./instance.js";
+import { scheduleLabelTextRebuild } from "./label-text-rebuild.js";
+import { catchReconcilerError } from "./reconciler-error-handler.js";
+import { getSignalStore } from "./signal-store.js";
+import { ensureState, type Node, stateOf } from "./state.js";
+import { scheduleBufferRebuild } from "./text-buffer-rebuild.js";
+import { isBufferContentNode, isLabelTextNode } from "./text-node.js";
+import type { Container, Props } from "./types.js";
+import { hideNode, reassertHidden, setTextNodeHidden, unhideNode } from "./visibility.js";
+import { isWrapperNode } from "./wrapper-node.js";
+import { BUFFER_TEXT_KIND, isWrapperKind, LABEL_TEXT_KIND, WRAPPER_NODE_ELEMENT } from "./wrapper-protocol.js";
+
+const FIXED_UPDATE_PRIORITY = DiscreteEventPriority;
+
+type PublicInstance = GObject.Object;
+
+type HostContext = {
+    textHost?: "label" | "buffer";
+};
+
+type HostConfig = ReactReconciler.HostConfig<
+    string,
+    Props,
+    Container,
+    Node,
+    Node,
+    never,
+    never,
+    never,
+    PublicInstance,
+    HostContext,
+    never,
+    number,
+    -1,
+    number
+>;
+
+export type ReconcilerInstance = ReactReconciler.Reconciler<Container, Node, Node, never, never, PublicInstance>;
+
+const link = (parent: Node, child: Node): void => {
+    const { children } = stateOf(parent);
+    const index = children.indexOf(child);
+    if (index !== -1) children.splice(index, 1);
+    children.push(child);
+    stateOf(child).parent = parent;
+};
+
+const linkBefore = (parent: Node, child: Node, before: Node): void => {
+    const { children } = stateOf(parent);
+    const existing = children.indexOf(child);
+    if (existing !== -1) children.splice(existing, 1);
+    const beforeIndex = children.indexOf(before);
+    if (beforeIndex === -1) children.push(child);
+    else children.splice(beforeIndex, 0, child);
+    stateOf(child).parent = parent;
+};
+
+const unlink = (parent: Node, child: Node): void => {
+    const { children } = stateOf(parent);
+    const index = children.indexOf(child);
+    if (index !== -1) children.splice(index, 1);
+    stateOf(child).parent = null;
+};
+
+const isBufferRelated = (instance: Node): boolean =>
+    isBufferContentNode(instance) || instance instanceof Gtk.TextTag || instance instanceof Gtk.TextBuffer;
+
+const scheduleTextRebuilds = (parent: Node, child: Node): void => {
+    if (isBufferRelated(parent) || isBufferRelated(child)) scheduleBufferRebuild(parent);
+    if (isLabelTextNode(child)) scheduleLabelTextRebuild(parent);
+};
+
+const reapplyParentLazy = (parent: Node): void => {
+    if (parent instanceof GObject.Object) reapplyLazyProps(parent, stateOf(parent).props);
+};
+
+const appendChild = (parent: Node, child: Node): void => {
+    const fresh = stateOf(child).parent === null;
+    link(parent, child);
+    attachNode(parent, child, null, fresh);
+    scheduleTextRebuilds(parent, child);
+    reapplyParentLazy(parent);
+};
+
+const insertBefore = (parent: Node, child: Node, before: Node): void => {
+    linkBefore(parent, child, before);
+    attachNode(parent, child, before, false);
+    scheduleTextRebuilds(parent, child);
+    reapplyParentLazy(parent);
+};
+
+const removeChild = (parent: Node, child: Node): void => {
+    scheduleTextRebuilds(parent, child);
+    unlink(parent, child);
+    detachNode(parent, child);
+};
+
+const commitInstanceProps = (instance: Node, oldProps: Props | null, newProps: Props): void => {
+    const state = stateOf(instance);
+    state.props = newProps;
+    if (isWrapperNode(instance)) {
+        if (isBufferContentNode(instance)) scheduleBufferRebuild(instance);
+        else resyncWrapperNode(instance);
+        reassertHidden(instance);
+        return;
+    }
+    if (!(instance instanceof GObject.Object)) return;
+    const excludeApplied = (name: string): boolean => isAppliedProp(instance.__type__, name);
+    const applyGenericAndSignals = (): void => {
+        if (instance instanceof Gtk.Accessible) {
+            applyAccessibleProps(instance, oldProps, newProps);
+            applyProps(instance, oldProps, newProps, {
+                exclude: (name) => isAccessibleProp(name) || excludeApplied(name),
+            });
+        } else {
+            applyProps(instance, oldProps, newProps, { exclude: excludeApplied });
+        }
+    };
+    if (oldProps === null) {
+        applyElementProps(instance, oldProps, newProps);
+        applyGenericAndSignals();
+    } else {
+        applyGenericAndSignals();
+        applyElementProps(instance, oldProps, newProps);
+    }
+    if (instance instanceof Gtk.TextTag) scheduleBufferRebuild(instance);
+    reassertHidden(instance);
+};
+
+const needsDetachOnDelete = (wrapper: GObject.Object): boolean =>
+    !(wrapper instanceof Gtk.Widget) && !(wrapper instanceof Gtk.TextBuffer);
+
+const detachInstance = (instance: Node): void => {
+    const state = stateOf(instance);
+    if (instance instanceof GObject.Object && needsDetachOnDelete(instance) && state.parent) {
+        detachFromParent(instance, state.parent);
+    }
+    if (instance instanceof GObject.Object) state.signalStore.clear(instance);
+};
+
+const createDetachGuard = (): ((instance: Node) => void) => {
+    const detached = new WeakSet<Node>();
+    return (instance: Node) => {
+        if (detached.has(instance)) return;
+        detached.add(instance);
+        detachInstance(instance);
+    };
+};
+
+type SchedulingConfig = Pick<
+    HostConfig,
+    | "supportsMutation"
+    | "supportsPersistence"
+    | "supportsHydration"
+    | "supportsMicrotasks"
+    | "scheduleMicrotask"
+    | "isPrimaryRenderer"
+    | "noTimeout"
+    | "scheduleTimeout"
+    | "cancelTimeout"
+    | "getCurrentUpdatePriority"
+    | "setCurrentUpdatePriority"
+    | "resolveUpdatePriority"
+>;
+
+const createSchedulingConfig = (): SchedulingConfig => ({
+    supportsMutation: true,
+    supportsPersistence: false,
+    supportsHydration: false,
+    supportsMicrotasks: true,
+    scheduleMicrotask: (fn: () => unknown) => queueMicrotask(fn),
+    isPrimaryRenderer: true,
+    noTimeout: -1,
+    scheduleTimeout: (fn, delay) => {
+        const timeoutId = setTimeout(fn, delay ?? 0);
+        return typeof timeoutId === "number" ? timeoutId : Number(timeoutId);
+    },
+    cancelTimeout: (id) => {
+        clearTimeout(id);
+    },
+    getCurrentUpdatePriority: () => FIXED_UPDATE_PRIORITY,
+    setCurrentUpdatePriority: () => {},
+    resolveUpdatePriority: () => FIXED_UPDATE_PRIORITY,
+});
+
+type HostContextConfig = Pick<HostConfig, "getRootHostContext" | "getChildHostContext" | "shouldSetTextContent">;
+
+const EMPTY_CONTEXT: HostContext = {};
+const LABEL_CONTEXT: HostContext = { textHost: "label" };
+const BUFFER_CONTEXT: HostContext = { textHost: "buffer" };
+
+type TextHostKind = "label" | "buffer" | "tag" | null;
+
+const textHostKinds = new Map<string, TextHostKind>();
+
+const resolveTextHostKind = (type: string): TextHostKind => {
+    const cached = textHostKinds.get(type);
+    if (cached !== undefined) return cached;
+    const gtype = GObject.typeFromName(type);
+    let kind: TextHostKind = null;
+    if (typeChainIncludes(gtype, "GtkLabel")) kind = "label";
+    else if (typeChainIncludes(gtype, "GtkTextBuffer")) kind = "buffer";
+    else if (typeChainIncludes(gtype, "GtkTextTag")) kind = "tag";
+    textHostKinds.set(type, kind);
+    return kind;
+};
+
+const createHostContextConfig = (): HostContextConfig => ({
+    getRootHostContext: () => EMPTY_CONTEXT,
+    getChildHostContext: (parentHostContext, type) => {
+        const kind = resolveTextHostKind(type);
+        if (kind === "label") return LABEL_CONTEXT;
+        if (kind === "buffer") return BUFFER_CONTEXT;
+        if (kind === "tag" && parentHostContext.textHost === "buffer") return parentHostContext;
+        return parentHostContext.textHost === undefined ? parentHostContext : EMPTY_CONTEXT;
+    },
+    shouldSetTextContent: () => false,
+});
+
+type InstanceConfig = Pick<
+    HostConfig,
+    "createInstance" | "createTextInstance" | "appendInitialChild" | "finalizeInitialChildren" | "getPublicInstance"
+>;
+
+const createInstanceConfig = (): InstanceConfig => ({
+    createInstance: (type, props, rootContainer) => {
+        if (type !== WRAPPER_NODE_ELEMENT) {
+            return createElementInstance(type, props, rootContainer);
+        }
+        const kind = props.kind;
+        if (!isWrapperKind(kind)) {
+            throw new Error(`Wrapper node element has an invalid kind: ${JSON.stringify(kind)}`);
+        }
+        return createWrapperInstance(kind, props, rootContainer);
+    },
+    createTextInstance: (text, rootContainer, hostContext) => {
+        if (hostContext.textHost === "buffer") {
+            return createWrapperInstance(BUFFER_TEXT_KIND, { text }, rootContainer);
+        }
+        if (hostContext.textHost === "label") {
+            return createWrapperInstance(LABEL_TEXT_KIND, { text }, rootContainer);
+        }
+        throw new Error(
+            `Text strings must be rendered within a <GtkLabel> or <GtkTextBuffer> element; received ${JSON.stringify(text)}`,
+        );
+    },
+    appendInitialChild: (parent, child) => {
+        appendChild(parent, child);
+    },
+    finalizeInitialChildren: (instance, _type, props) => {
+        commitInstanceProps(instance, null, props);
+        return false;
+    },
+    getPublicInstance: (instance) => {
+        const adopted = isWrapperNode(instance) ? stateOf(instance).adoptedInstance : undefined;
+        return (adopted ?? instance) as PublicInstance;
+    },
+});
+
+type MutationConfig = Pick<
+    HostConfig,
+    | "appendChild"
+    | "removeChild"
+    | "insertBefore"
+    | "appendChildToContainer"
+    | "removeChildFromContainer"
+    | "insertInContainerBefore"
+    | "clearContainer"
+    | "hideInstance"
+    | "unhideInstance"
+    | "hideTextInstance"
+    | "unhideTextInstance"
+>;
+
+const createMutationConfig = (): MutationConfig => ({
+    appendChild: (parent, child) => {
+        appendChild(parent, child);
+    },
+    removeChild: (parent, child) => {
+        removeChild(parent, child);
+    },
+    insertBefore: (parent, child, beforeChild) => {
+        insertBefore(parent, child, beforeChild);
+    },
+    removeChildFromContainer: (container, child) => {
+        ensureState(container);
+        removeChild(container, child);
+    },
+    appendChildToContainer: (container, child) => {
+        ensureState(container);
+        appendChild(container, child);
+    },
+    insertInContainerBefore: (container, child, beforeChild) => {
+        ensureState(container);
+        insertBefore(container, child, beforeChild);
+    },
+    clearContainer: () => {},
+    hideInstance: (instance) => {
+        hideNode(instance);
+    },
+    unhideInstance: (instance) => {
+        unhideNode(instance);
+    },
+    hideTextInstance: (textInstance) => {
+        setTextNodeHidden(textInstance, true);
+    },
+    unhideTextInstance: (textInstance) => {
+        setTextNodeHidden(textInstance, false);
+    },
+});
+
+type CommitConfig = Pick<HostConfig, "commitUpdate" | "commitTextUpdate" | "prepareForCommit" | "resetAfterCommit">;
+
+const drainCommitQueue = (): void => catchReconcilerError(runCommitFlush);
+
+const finalizeCommitAfterLayoutEffects = (container: Container): void => {
+    drainCommitQueue();
+    getSignalStore(container).unblock();
+};
+
+const createCommitConfig = (): CommitConfig => ({
+    commitUpdate: (instance, _type, oldProps, newProps) => commitInstanceProps(instance, oldProps, newProps),
+    commitTextUpdate: (textInstance, _oldText, newText) => {
+        stateOf(textInstance).props = { text: newText };
+        if (isBufferContentNode(textInstance)) scheduleBufferRebuild(textInstance);
+        else scheduleLabelTextRebuild(textInstance);
+    },
+    prepareForCommit: (container) => {
+        getSignalStore(container).block();
+        return null;
+    },
+    resetAfterCommit: (container) => {
+        drainCommitQueue();
+        queueMicrotask(() => finalizeCommitAfterLayoutEffects(container));
+    },
+});
+
+type NoopConfig = Pick<
+    HostConfig,
+    | "preparePortalMount"
+    | "NotPendingTransition"
+    | "HostTransitionContext"
+    | "getInstanceFromNode"
+    | "beforeActiveInstanceBlur"
+    | "afterActiveInstanceBlur"
+    | "prepareScopeUpdate"
+    | "getInstanceFromScope"
+    | "resetFormInstance"
+    | "requestPostPaintCallback"
+    | "shouldAttemptEagerTransition"
+    | "trackSchedulerEvent"
+    | "resolveEventType"
+    | "resolveEventTimeStamp"
+    | "maySuspendCommit"
+    | "preloadInstance"
+    | "startSuspendingCommit"
+    | "suspendInstance"
+    | "waitForCommitToBeReady"
+>;
+
+const createNoopConfig = (): NoopConfig => ({
+    preparePortalMount: () => {},
+    NotPendingTransition: null,
+    HostTransitionContext: createContext(0) as Context<number> & ReactReconciler.ReactContext<number>,
+    getInstanceFromNode: () => null,
+    beforeActiveInstanceBlur: () => {},
+    afterActiveInstanceBlur: () => {},
+    prepareScopeUpdate: () => {},
+    getInstanceFromScope: () => null,
+    resetFormInstance: () => {},
+    requestPostPaintCallback: () => {},
+    shouldAttemptEagerTransition: () => false,
+    trackSchedulerEvent: () => {},
+    resolveEventType: () => null,
+    resolveEventTimeStamp: () => Date.now(),
+    maySuspendCommit: () => false,
+    preloadInstance: () => false,
+    startSuspendingCommit: () => {},
+    suspendInstance: () => {},
+    waitForCommitToBeReady: () => null,
+});
+
+export function createHostConfig(): HostConfig {
+    return {
+        ...createSchedulingConfig(),
+        ...createHostContextConfig(),
+        ...createInstanceConfig(),
+        ...createMutationConfig(),
+        ...createCommitConfig(),
+        ...createNoopConfig(),
+        detachDeletedInstance: createDetachGuard(),
+    };
+}

package/src/reconciler/instance.ts

@@ -0,0 +1,30 @@
+import * as GObject from "@gtkx/gi/gobject";
+import { collectConstructableProps, requireClassByName } from "../utils/gtype.js";
+import { constructionSkipProps } from "./element-props.js";
+import { type Node, registerState } from "./state.js";
+import type { Container, Props } from "./types.js";
+import { createWrapperNode } from "./wrapper-node.js";
+import type { WrapperKind } from "./wrapper-protocol.js";
+
+const pickConstructProps = (gtype: bigint, props: Props): Props => {
+    const constructable = collectConstructableProps(gtype);
+    const skipped = constructionSkipProps(gtype);
+    const result: Props = {};
+    for (const name in props) {
+        if (constructable.has(name) && !skipped.has(name)) result[name] = props[name];
+    }
+    return result;
+};
+
+export const createElementInstance = (type: string, props: Props, rootContainer: Container): Node => {
+    const cls = requireClassByName(type);
+    const node = new cls(pickConstructProps(GObject.typeFromName(type), props));
+    registerState(node, { props, rootContainer });
+    return node;
+};
+
+export const createWrapperInstance = (kind: WrapperKind, props: Props, rootContainer: Container): Node => {
+    const node = createWrapperNode();
+    registerState(node, { kind, props, rootContainer });
+    return node;
+};

package/src/reconciler/label-text-rebuild.ts

@@ -0,0 +1,26 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { scheduleContentRebuild } from "./content-rebuild.js";
+import { type Node, stateOf } from "./state.js";
+import { isLabelTextNode } from "./text-node.js";
+
+const rebuildLabelText = (owner: Gtk.Label): void => {
+    const state = stateOf(owner);
+    const runs = state.children.filter(isLabelTextNode);
+    if (state.props.label !== undefined) {
+        if (runs.length === 0) return;
+        throw new Error("<GtkLabel> cannot mix a `label` prop with text children; use one or the other");
+    }
+    const text = runs
+        .filter((run) => !stateOf(run).hidden)
+        .map((run) => String(stateOf(run).props.text))
+        .join("");
+    owner.setLabel(text);
+};
+
+export const scheduleLabelTextRebuild = (node: Node): void => {
+    scheduleContentRebuild(
+        node,
+        (candidate): candidate is Gtk.Label => candidate instanceof Gtk.Label,
+        (owner) => () => rebuildLabelText(owner),
+    );
+};

package/src/reconciler/portal.ts

@@ -0,0 +1,28 @@
+import type { ReactNode, ReactPortal } from "react";
+import type { Container } from "./types.js";
+
+type ObjectPortal = ReactPortal & {
+    $$typeof: symbol;
+    containerInfo: Container;
+    implementation: null;
+};
+
+/**
+ * Creates a React portal that renders `children` into a different container in the widget tree.
+ *
+ * @param children The nodes to render inside the container.
+ * @param container The GObject or root element to render into.
+ * @param key An optional React key for the portal.
+ */
+export const createPortal = (children: ReactNode, container: Container, key?: string | null): ReactPortal => {
+    const portal: ObjectPortal = {
+        $$typeof: Symbol.for("react.portal"),
+        type: "",
+        props: { children },
+        key: key ?? null,
+        children,
+        containerInfo: container,
+        implementation: null,
+    };
+    return portal;
+};

package/src/reconciler/reconciler-error-handler.ts

@@ -0,0 +1,29 @@
+import { createLogger, type Logger } from "@gtkx/utils";
+
+export const log: Logger = createLogger("react");
+
+export type ReconcilerErrorHandler = (error: unknown) => void;
+
+let errorHandler: ReconcilerErrorHandler | null = null;
+
+export function setReconcilerErrorHandler(handler: ReconcilerErrorHandler | null): ReconcilerErrorHandler | null {
+    const prior = errorHandler;
+    errorHandler = handler;
+    return prior;
+}
+
+export function reportReconcilerError(error: unknown): void {
+    if (errorHandler) {
+        errorHandler(error);
+        return;
+    }
+    log.error("unhandled reconciler error", error);
+}
+
+export function catchReconcilerError(fn: () => void): void {
+    try {
+        fn();
+    } catch (error) {
+        reportReconcilerError(error);
+    }
+}

package/src/reconciler/reconciler-root.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from "react";
+import { reconciler } from "./reconciler.js";
+import type { Container } from "./types.js";
+
+const noop = (): void => {};
+
+type FiberRoot = ReturnType<typeof reconciler.createContainer>;
+
+type ReconcilerErrorCallback = (error: Error, info: { componentStack?: string | null }) => void;
+
+export type ReconcilerRootOptions = {
+    containerInfo: Container;
+    onUncaughtError: ReconcilerErrorCallback;
+    onCaughtError: ReconcilerErrorCallback;
+    onRecoverableError?: ReconcilerErrorCallback;
+};
+
+export type ReconcilerRoot = {
+    update(element: ReactNode): void;
+    unmount<R>(free: (root: ReconcilerRoot) => R): R | undefined;
+};
+
+const activeRoots = new Set<ReconcilerRoot>();
+
+export const createReconcilerRoot = (options: ReconcilerRootOptions): ReconcilerRoot => {
+    const fiberRoot: FiberRoot = reconciler.createContainer(
+        options.containerInfo,
+        1,
+        null,
+        false,
+        null,
+        "",
+        options.onUncaughtError,
+        options.onCaughtError,
+        options.onRecoverableError ?? noop,
+        noop,
+    );
+
+    const root: ReconcilerRoot = {
+        update: (element: ReactNode): void => {
+            reconciler.updateContainer(element, fiberRoot, null, noop);
+        },
+        unmount: <R>(free: (root: ReconcilerRoot) => R): R | undefined => {
+            if (!activeRoots.delete(root)) return undefined;
+            return free(root);
+        },
+    };
+
+    activeRoots.add(root);
+    return root;
+};
+
+export const unmountAllReconcilerRoots = (free: (root: ReconcilerRoot) => void): void => {
+    const roots = [...activeRoots];
+    activeRoots.clear();
+    roots.forEach(free);
+};

package/src/reconciler/reconciler.ts

@@ -0,0 +1,13 @@
+import ReactReconciler from "react-reconciler";
+import packageJson from "../../package.json" with { type: "json" };
+import { createHostConfig, type ReconcilerInstance } from "./host-config.js";
+
+export const reconciler: ReconcilerInstance = ReactReconciler(createHostConfig());
+
+if (process.env.NODE_ENV !== "production") {
+    reconciler.injectIntoDevTools({
+        bundleType: 1,
+        version: packageJson.version,
+        rendererPackageName: "@gtkx/react",
+    });
+}

package/src/reconciler/render.ts

@@ -0,0 +1,61 @@
+import type { ReactNode } from "react";
+import { log, type ReconcilerErrorHandler, setReconcilerErrorHandler } from "./reconciler-error-handler.js";
+import { createReconcilerRoot, type ReconcilerRoot, unmountAllReconcilerRoots } from "./reconciler-root.js";
+import { type RootElement, rootElement } from "./root-element.js";
+import { getSignalStore } from "./signal-store.js";
+
+const priorHandlers = new WeakMap<ReconcilerRoot, ReconcilerErrorHandler | null>();
+
+const teardownRoot = (root: ReconcilerRoot): void => {
+    setReconcilerErrorHandler(priorHandlers.get(root) ?? null);
+    root.update(null);
+};
+
+/**
+ * A render root that mounts a React element tree into a container and can unmount it.
+ */
+export type Root = {
+    render(element: ReactNode): void;
+    unmount(): void;
+};
+
+/**
+ * Creates a render root for a container, wiring reconciler error handling to the container's signal store.
+ *
+ * @param container The root element to render into; defaults to the shared `rootElement`.
+ * @returns A root with `render` and `unmount` methods.
+ */
+export const createRoot = (container: RootElement = rootElement): Root => {
+    const onUncaughtError = (error: unknown): void => {
+        getSignalStore(container).unblock();
+        throw error;
+    };
+    const onCaughtError = (error: unknown): void => {
+        getSignalStore(container).unblock();
+        log.error("caught render error", error);
+    };
+
+    const priorHandler = setReconcilerErrorHandler(onUncaughtError);
+
+    const root = createReconcilerRoot({ containerInfo: container, onUncaughtError, onCaughtError });
+    priorHandlers.set(root, priorHandler);
+
+    return {
+        render: (element: ReactNode): void => {
+            root.update(element);
+        },
+        unmount: (): void => {
+            root.unmount(teardownRoot);
+        },
+    };
+};
+
+/**
+ * Unmounts all active render roots.
+ *
+ * @returns `true` once every root has been torn down.
+ */
+export const quit = (): true => {
+    unmountAllReconcilerRoots(teardownRoot);
+    return true;
+};

package/src/reconciler/root-element.ts

@@ -0,0 +1,14 @@
+const ROOT_ELEMENT: unique symbol = Symbol.for("gtkx.rootElement");
+
+/**
+ * The type of the singleton marker used as the top-level render container.
+ */
+export type RootElement = { [ROOT_ELEMENT]: true };
+
+/**
+ * The shared root element used as the default container for `createRoot`.
+ */
+export const rootElement: RootElement = { [ROOT_ELEMENT]: true };
+
+export const isRootElement = (value: unknown): value is RootElement =>
+    typeof value === "object" && value !== null && ROOT_ELEMENT in value;