onejs-react 0.1.26 → 0.1.28

package/README.md

@@ -98,6 +98,12 @@ import { render, RenderContainer } from "onejs-react"
 render(<App />, __root)
 ```
 
+### Unmounting & hot-reload teardown
+
+`unmount(container)` tears a root down **synchronously** (`updateContainerSync` + `flushSyncWork` + `flushPassiveEffects`), so `useEffect`/`useLayoutEffect` cleanup functions fire immediately instead of on a later scheduler tick. `unmountAll()` does the same for every active root.
+
+The first `render()` call registers `unmountAll` as a runtime teardown hook (`globalThis.__onTeardown`). The OneJS runtime invokes it right before destroying the JS context on hot reload / stop, so component cleanups run while the context is still alive. Without this, cleanups would be skipped on hot reload and stale C# subscriptions (e.g. from `useEventSync`) would leak across reloads.
+
 ### Type Hierarchy
 
 ```
@@ -114,24 +120,27 @@ RenderContainer         (minimal: __csHandle, __csType)
 
 ### Portals
 
-`createPortal(children, container, key?)` renders a subtree into a different `VisualElement`, outside the normal parent hierarchy - the OneJS equivalent of `react-dom`'s `createPortal`.
-
-UI Toolkit has no `z-index`: paint order follows the element hierarchy and a parent with `overflow: hidden` clips its children. Portaling overlays (modals, tooltips, dropdowns) into a top-level container like `__root` lets them escape clipping and paint above the rest of the UI.
+`<Portal>` renders children above the rest of the UI (modals, tooltips, dropdowns). UI Toolkit has no `z-index` and `overflow: hidden` clips children, so a deeply-nested overlay gets clipped and stuck below later siblings. `<Portal>` mounts into a shared overlay layer that onejs-react keeps as the last child of `__root`, so overlays always paint on top. Zero setup.
 
 ```tsx
-import { createPortal, View } from "onejs-react"
+import { Portal, View } from "onejs-react"
 
 function Modal({ children }) {
-    return createPortal(
-        <View style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 }}>
-            {children}
-        </View>,
-        __root
+    return (
+        <Portal>
+            <View style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 }}>
+                {children}
+            </View>
+        </Portal>
     )
 }
 ```
 
-> Use the `createPortal` exported from `onejs-react`, not the one from `react-dom` - the latter targets the browser DOM and will not work here.
+The layer ignores picking when empty, so a closed overlay never blocks the app.
+
+`<Portal>` is built on `createPortal(children, container, key?)` (the OneJS equivalent of `react-dom`'s `createPortal`), exported for when you need a specific target. With a custom target you own draw order, so prefer `<Portal>` for overlays.
+
+> Use the exports from `onejs-react`, not `react-dom` - the latter targets the browser DOM and will not work here.
 
 ## Key Concepts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onejs-react",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "React 19 renderer for OneJS (Unity UI Toolkit)",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/__tests__/mocks.ts

@@ -60,6 +60,7 @@ export class MockVisualElement {
 
     // Child management
     private _children: MockVisualElement[] = [];
+    private _parent: MockVisualElement | null = null;
 
     // Style object (simulates IStyle)
     style: Record<string, unknown> = {};
@@ -73,6 +74,7 @@ export class MockVisualElement {
     value: unknown = undefined;
     label = '';
     enabledSelf = true;
+    pickingMode = 0;
 
     constructor(csType = 'UnityEngine.UIElements.VisualElement') {
         this.__csHandle = Math.floor(Math.random() * 1000000);
@@ -84,6 +86,7 @@ export class MockVisualElement {
     Add(child: MockVisualElement): void {
         if (child && !this._children.includes(child)) {
             this._children.push(child);
+            child._parent = this;
         }
     }
 
@@ -95,6 +98,7 @@ export class MockVisualElement {
                 this._children.splice(existingIndex, 1);
             }
             this._children.splice(index, 0, child);
+            child._parent = this;
         }
     }
 
@@ -102,20 +106,29 @@ export class MockVisualElement {
         const index = this._children.indexOf(child);
         if (index >= 0) {
             this._children.splice(index, 1);
+            child._parent = null;
         }
     }
 
     RemoveAt(index: number): void {
         if (index >= 0 && index < this._children.length) {
-            this._children.splice(index, 1);
+            const [child] = this._children.splice(index, 1);
+            if (child) child._parent = null;
         }
     }
 
+    // Mirrors UnityEngine.UIElements.VisualElement.RemoveFromHierarchy(): detach from
+    // the current parent, a no-op when already detached.
+    RemoveFromHierarchy(): void {
+        this._parent?.Remove(this);
+    }
+
     IndexOf(child: MockVisualElement): number {
         return this._children.indexOf(child);
     }
 
     Clear(): void {
+        for (const child of this._children) child._parent = null;
         this._children = [];
     }
 

package/src/__tests__/portal.test.tsx

@@ -0,0 +1,85 @@
+/**
+ * Tests for the <Portal> component.
+ *
+ * Portal renders into a shared overlay layer that OneJS keeps as the last child
+ * of __root, so overlays paint on top of the app without per-call BringToFront.
+ */
+
+import { describe, it, expect } from 'vitest';
+import React from 'react';
+import { render } from '../renderer';
+import { Portal } from '../portal';
+import { View, Label, Button } from '../components';
+import { MockVisualElement, createMockContainer, flushMicrotasks } from './mocks';
+
+describe('Portal', () => {
+    it('mounts children into a shared overlay layer appended last under __root', async () => {
+        const root = createMockContainer();
+        (globalThis as any).__root = root;
+
+        render(<View><Portal><Label text="overlay" /></Portal></View>, root as any);
+        await flushMicrotasks();
+
+        // root children: [0] app view, [1] portal layer (added in an effect → last)
+        expect(root.childCount).toBe(2);
+        const layer = root.children[1] as MockVisualElement;
+        expect(layer.name).toBe('onejs-portal-root');
+        expect(layer.pickingMode).toBe((globalThis as any).CS.UnityEngine.UIElements.PickingMode.Ignore);
+
+        // portal content lives inside the layer, not the app view
+        expect(layer.childCount).toBe(1);
+        expect(layer.children[0].__csType).toBe('UnityEngine.UIElements.Label');
+        expect((root.children[0] as MockVisualElement).childCount).toBe(0);
+    });
+
+    it('shares one layer across multiple Portals', async () => {
+        const root = createMockContainer();
+        (globalThis as any).__root = root;
+
+        render(
+            <View>
+                <Portal><Label text="a" /></Portal>
+                <Portal><Button text="b" /></Portal>
+            </View>,
+            root as any
+        );
+        await flushMicrotasks();
+
+        // app + exactly one shared layer
+        expect(root.childCount).toBe(2);
+        const layer = root.children[1] as MockVisualElement;
+        expect(layer.childCount).toBe(2);
+    });
+
+    it('targets an explicit container without creating the shared layer', async () => {
+        const root = createMockContainer();
+        (globalThis as any).__root = root;
+        const target = createMockContainer();
+
+        render(<View><Portal container={target as any}><Label text="x" /></Portal></View>, root as any);
+        await flushMicrotasks();
+
+        expect(target.childCount).toBe(1);
+        expect(target.children[0].__csType).toBe('UnityEngine.UIElements.Label');
+        // shared layer not created: root has only the app view
+        expect(root.childCount).toBe(1);
+    });
+
+    it('removes portal content when unmounted', async () => {
+        const root = createMockContainer();
+        (globalThis as any).__root = root;
+
+        function App({ show }: { show: boolean }) {
+            return <View>{show && <Portal><Label text="m" /></Portal>}</View>;
+        }
+
+        render(<App show={true} />, root as any);
+        await flushMicrotasks();
+        const layer = root.children[1] as MockVisualElement;
+        expect(layer.childCount).toBe(1);
+
+        render(<App show={false} />, root as any);
+        await flushMicrotasks();
+        expect(layer.childCount).toBe(0);
+    });
+});

package/src/__tests__/renderer.test.tsx

@@ -10,7 +10,7 @@
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import React, { useState, useEffect } from 'react';
-import { render, unmount, createPortal, getRoot } from '../renderer';
+import { render, unmount, unmountAll, createPortal, getRoot } from '../renderer';
 import { View, Label, Button } from '../components';
 import { MockVisualElement, MockLength, MockColor, createMockContainer, flushMicrotasks, getEventAPI } from './mocks';
 
@@ -402,6 +402,56 @@ describe('renderer', () => {
 
             expect(cleanupFn).toHaveBeenCalled();
         });
+
+        it('fires effect cleanup synchronously on unmount (no tick needed)', async () => {
+            // On hot-reload teardown the JS context is destroyed immediately after
+            // unmount, so cleanups must run synchronously rather than on a later tick.
+            const container = createMockContainer();
+            const cleanupFn = vi.fn();
+
+            function CleanupComponent() {
+                useEffect(() => cleanupFn, []);
+                return <ojs-view />;
+            }
+
+            render(<CleanupComponent />, container as any);
+            await flushMicrotasks();
+            expect(cleanupFn).not.toHaveBeenCalled();
+
+            unmount(container as any);
+            // No flushMicrotasks: cleanup must already have run.
+            expect(cleanupFn).toHaveBeenCalledTimes(1);
+            expect(getRoot(container as any)).toBeUndefined();
+        });
+
+        it('unmountAll tears down every root and fires cleanups (hot reload)', async () => {
+            // unmountAll is what the runtime teardown hook (__runTeardown) invokes
+            // before destroying the context on hot reload / stop.
+            const containerA = createMockContainer();
+            const containerB = createMockContainer();
+            const cleanupA = vi.fn();
+            const cleanupB = vi.fn();
+
+            function CompA() {
+                useEffect(() => cleanupA, []);
+                return <ojs-view />;
+            }
+            function CompB() {
+                useEffect(() => cleanupB, []);
+                return <ojs-view />;
+            }
+
+            render(<CompA />, containerA as any);
+            render(<CompB />, containerB as any);
+            await flushMicrotasks();
+
+            unmountAll();
+
+            expect(cleanupA).toHaveBeenCalledTimes(1);
+            expect(cleanupB).toHaveBeenCalledTimes(1);
+            expect(getRoot(containerA as any)).toBeUndefined();
+            expect(getRoot(containerB as any)).toBeUndefined();
+        });
     });
 
     describe('conditional rendering', () => {

package/src/host-config.ts

@@ -86,6 +86,10 @@ declare const __eventAPI: {
     removeParent: (childHandle: number) => void;
 };
 
+// Panel root element, provided by the runtime. This is also the container apps
+// pass to render(), so it is the natural home for a shared overlay layer.
+declare const __root: CSObject;
+
 interface CSStyle {
     [key: string]: unknown;
 }
@@ -437,6 +441,34 @@ function applyStyle(element: CSObject, style: ViewStyle | undefined): Set<string
     return appliedKeys;
 }
 
+// Shared overlay layer for <Portal>. A full-screen, click-through element kept as
+// the LAST child of __root, so portaled content (modals, tooltips, dropdowns)
+// always paints above the app and escapes any `overflow: hidden` ancestor.
+//
+// It must be appended AFTER the app's root view exists, otherwise it lands before
+// the app and renders behind it. Callers create it from an effect (post-mount), by
+// which point the app root is already in __root, so Add() puts the layer last.
+//
+// Keyed by __root so a fresh root (e.g. after a domain reload) gets its own layer.
+const _portalLayers = new WeakMap<object, VisualElement>();
+
+export function getPortalLayer(): VisualElement {
+    const root = __root as unknown as object;
+    let layer = _portalLayers.get(root);
+    if (!layer) {
+        const el: CSObject = new CS.UnityEngine.UIElements.VisualElement();
+        el.name = "onejs-portal-root";
+        applyStyle(el, { position: "absolute", top: 0, left: 0, right: 0, bottom: 0 });
+        // The layer itself ignores picking so empty regions stay click-through; its
+        // children (modals, etc.) still receive input normally.
+        el.pickingMode = CS.UnityEngine.UIElements.PickingMode.Ignore;
+        __root.Add(el);
+        layer = el;
+        _portalLayers.set(root, layer);
+    }
+    return layer;
+}
+
 // Force-resolve CS path proxies (e.g. CS.UnityEngine.UIElements.Justify.Center)
 // to their underlying int value. parseEnumValue and parseLength's StyleKeyword
 // cases return path proxies whose .valueOf() reads the int via GetField. The
@@ -1100,14 +1132,20 @@ export const hostConfig = {
             removeMergedTextChild(parentInstance, child);
         } else {
             __eventAPI.removeAllEventListeners(child.element);
-            parentInstance.element.Remove(child.element);
+            // RemoveFromHierarchy() detaches the element from its current parent and
+            // is a safe no-op if it's already detached. Using it instead of
+            // parentInstance.element.Remove(child.element) keeps unmount from throwing
+            // when the root was cleared before React tore the tree down (hot reload).
+            child.element.RemoveFromHierarchy();
         }
         untrackParent(child.element);
     },
 
     removeChildFromContainer(container: Container, child: Instance) {
         __eventAPI.removeAllEventListeners(child.element);
-        container.Remove(child.element);
+        // See removeChild: tolerant of an already-detached element so a hot-reload
+        // teardown (which clears the root first) can still unmount cleanly.
+        child.element.RemoveFromHierarchy();
         untrackParent(child.element);
     },
 

package/src/index.ts

@@ -19,7 +19,11 @@ export {
 export { registerElement } from './host-config';
 
 // Renderer
-export { render, unmount, createPortal, flushSync, batchedUpdates, getDebugInfo } from './renderer';
+export { render, unmount, unmountAll, createPortal, flushSync, batchedUpdates, getDebugInfo } from './renderer';
+
+// Portals
+export { Portal } from './portal';
+export type { PortalProps } from './portal';
 
 // Error Handling
 export { ErrorBoundary, formatError } from './error-boundary';

package/src/portal.tsx

@@ -0,0 +1,51 @@
+import { useState, useEffect, type ReactNode } from "react"
+import { createPortal } from "./renderer"
+import { getPortalLayer } from "./host-config"
+import type { RenderContainer } from "./types"
+
+export interface PortalProps {
+    children: ReactNode
+    /** Target element. Defaults to OneJS's shared overlay layer (last child of `__root`). */
+    container?: RenderContainer
+}
+
+/**
+ * Render `children` above the rest of the UI, outside the normal hierarchy.
+ *
+ * Zero setup: portals into a shared overlay layer that OneJS keeps as the last
+ * child of `__root`, so modals, tooltips, and dropdowns always paint on top and
+ * escape any `overflow: hidden` ancestor. Pass `container` to target a specific
+ * element instead.
+ *
+ * Built on {@link createPortal}; reach for that directly only when you need a
+ * custom target and want to manage draw order yourself.
+ *
+ * @example
+ * function Modal({ onClose, children }) {
+ *     return (
+ *         <Portal>
+ *             <View
+ *                 style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0,
+ *                          backgroundColor: "rgba(0,0,0,0.6)", alignItems: "center", justifyContent: "center" }}
+ *                 onClick={onClose}
+ *             >
+ *                 <View onClick={(e) => e.stopPropagation()}>{children}</View>
+ *             </View>
+ *         </Portal>
+ *     )
+ * }
+ */
+export function Portal({ children, container }: PortalProps) {
+    // The shared layer is appended to __root in an effect (after the app mounts) so
+    // it lands last. It is therefore unavailable on the first render; we resolve it
+    // post-mount, which adds one frame before the overlay appears. An explicit
+    // container is used immediately, with no delay.
+    const [layer, setLayer] = useState<RenderContainer | null>(container ?? null)
+
+    useEffect(() => {
+        if (!container) setLayer(getPortalLayer())
+    }, [container])
+
+    const target = container ?? layer
+    return target ? createPortal(children, target) : null
+}

package/src/renderer.ts

@@ -19,7 +19,24 @@ reconciler.injectIntoDevTools({
 // Track roots for hot reload / re-render
 const roots = new Map<RenderContainer, ReturnType<typeof reconciler.createContainer>>();
 
+// Register unmountAll as a runtime teardown hook exactly once. The OneJS runtime
+// (QuickJSUIBridge.Dispose) invokes __runTeardown() right before destroying the JS
+// context on hot reload / stop. Unmounting here fires useEffect/useLayoutEffect
+// cleanups while the context is still alive; otherwise they never run and stale
+// C# subscriptions (e.g. from useEventSync) leak across reloads.
+let teardownHookRegistered = false;
+function ensureTeardownHook(): void {
+  if (teardownHookRegistered) return;
+  const g = globalThis as any;
+  if (typeof g !== 'undefined' && typeof g.__onTeardown === 'function') {
+    g.__onTeardown(unmountAll);
+    teardownHookRegistered = true;
+  }
+}
+
 export function render(element: ReactNode, container: RenderContainer): void {
+  ensureTeardownHook();
+
   let root = roots.get(container);
 
   if (!root) {
@@ -52,9 +69,33 @@ export function render(element: ReactNode, container: RenderContainer): void {
 
 export function unmount(container: RenderContainer): void {
   const root = roots.get(container);
-  if (root) {
+  if (!root) return;
+  roots.delete(container);
+
+  const r = reconciler as any;
+  // Tear the tree down synchronously. updateContainer(null, ...) only *schedules*
+  // the unmount, which never gets a scheduler tick during a hot-reload teardown
+  // (the context is destroyed immediately after). updateContainerSync + flushSyncWork
+  // runs the commit now, firing useLayoutEffect cleanups during it.
+  if (typeof r.updateContainerSync === 'function') {
+    r.updateContainerSync(null, root, null, null);
+    if (typeof r.flushSyncWork === 'function') r.flushSyncWork();
+  } else {
     reconciler.updateContainer(null, root, null, () => {});
-    roots.delete(container);
+  }
+  // useEffect (passive) cleanups are queued by the unmount commit, not run by it.
+  // Flush them now so they also fire before the context goes away.
+  if (typeof r.flushPassiveEffects === 'function') r.flushPassiveEffects();
+}
+
+/**
+ * Unmount every active root. Invoked by the OneJS runtime teardown hook before the
+ * JS context is destroyed (hot reload / stop) so component cleanups run.
+ */
+export function unmountAll(): void {
+  // Snapshot keys first: unmount() mutates the roots map.
+  for (const container of Array.from(roots.keys())) {
+    unmount(container);
   }
 }
 

package/src/types.ts

@@ -675,6 +675,7 @@ export interface VisualElement extends RenderContainer {
   Insert: (index: number, child: VisualElement) => void;
   Remove: (child: VisualElement) => void;
   RemoveAt: (index: number) => void;
+  RemoveFromHierarchy: () => void;
   Clear: () => void;
   IndexOf: (child: VisualElement) => number;
   childCount: number;