onejs-react 0.1.7 → 0.1.9

package/package.json

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

package/src/__tests__/hooks.test.tsx

@@ -0,0 +1,581 @@
+/**
+ * Tests for C# interop hooks and utilities
+ *
+ * Tests cover:
+ * - toArray: Converting C# collections (List<T>, arrays) to JS arrays
+ * - useFrameSync (simple mode): Object.is comparison for primitives
+ * - useFrameSync (selector mode): Deps-based change detection for C# proxy objects
+ * - useFrameSyncWith (deprecated): Custom equality comparison
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
+import React from "react"
+import { useFrameSync, useFrameSyncWith, toArray } from "../hooks"
+import { render, unmount } from "../renderer"
+import { createMockContainer, flushMicrotasks } from "./mocks"
+
+// ---------------------------------------------------------------------------
+// RAF mock — needed because hooks use requestAnimationFrame for polling
+// ---------------------------------------------------------------------------
+
+type RafCallback = (time: number) => void
+
+let rafQueue: Array<{ id: number; callback: RafCallback }> = []
+let nextRafId = 0
+
+/** Flush all pending requestAnimationFrame callbacks (one round). */
+function flushRaf() {
+    const queue = [...rafQueue]
+    rafQueue = []
+    const now = Date.now()
+    for (const { callback } of queue) {
+        callback(now)
+    }
+}
+
+/** Flush RAF then microtasks — simulates a full frame tick for the hook. */
+async function advanceFrame() {
+    flushRaf()
+    await flushMicrotasks()
+}
+
+beforeEach(() => {
+    rafQueue = []
+    nextRafId = 0
+    ;(globalThis as any).requestAnimationFrame = vi.fn((cb: RafCallback) => {
+        const id = ++nextRafId
+        rafQueue.push({ id, callback: cb })
+        return id
+    })
+    ;(globalThis as any).cancelAnimationFrame = vi.fn((id: number) => {
+        rafQueue = rafQueue.filter((e) => e.id !== id)
+    })
+})
+
+afterEach(() => {
+    delete (globalThis as any).requestAnimationFrame
+    delete (globalThis as any).cancelAnimationFrame
+})
+
+// ===========================================================================
+// toArray
+// ===========================================================================
+
+describe("toArray", () => {
+    it("returns empty array for null", () => {
+        expect(toArray(null)).toEqual([])
+    })
+
+    it("returns empty array for undefined", () => {
+        expect(toArray(undefined)).toEqual([])
+    })
+
+    it("converts a C# List (Count property)", () => {
+        const mockList: Record<string, unknown> = {
+            Count: 3,
+            0: "alpha",
+            1: "beta",
+            2: "gamma",
+        }
+        expect(toArray(mockList)).toEqual(["alpha", "beta", "gamma"])
+    })
+
+    it("converts a C# array (Length property)", () => {
+        const mockArray: Record<string, unknown> = {
+            Length: 2,
+            0: 10,
+            1: 20,
+        }
+        expect(toArray(mockArray)).toEqual([10, 20])
+    })
+
+    it("returns empty array for empty collection with Count=0", () => {
+        expect(toArray({ Count: 0 })).toEqual([])
+    })
+
+    it("returns empty array for empty collection with Length=0", () => {
+        expect(toArray({ Length: 0 })).toEqual([])
+    })
+
+    it("prefers Count over Length when both exist", () => {
+        const mock: Record<string, unknown> = {
+            Count: 2,
+            Length: 3,
+            0: "x",
+            1: "y",
+            2: "z",
+        }
+        // Should use Count (2), not Length (3)
+        expect(toArray(mock)).toEqual(["x", "y"])
+    })
+
+    it("returns empty array for objects without Count or Length", () => {
+        expect(toArray({})).toEqual([])
+        expect(toArray({ foo: "bar" })).toEqual([])
+    })
+
+    it("returns empty array for non-numeric Count/Length", () => {
+        expect(toArray({ Count: "not a number" })).toEqual([])
+        expect(toArray({ Length: null })).toEqual([])
+        expect(toArray({ Count: true })).toEqual([])
+    })
+
+    it("handles collection with object elements", () => {
+        const mockList: Record<string, unknown> = {
+            Count: 2,
+            0: { id: 1, name: "Sword" },
+            1: { id: 2, name: "Shield" },
+        }
+        const result = toArray<{ id: number; name: string }>(mockList)
+        expect(result).toHaveLength(2)
+        expect(result[0].id).toBe(1)
+        expect(result[0].name).toBe("Sword")
+        expect(result[1].id).toBe(2)
+        expect(result[1].name).toBe("Shield")
+    })
+
+    it("handles single-element collection", () => {
+        expect(toArray({ Count: 1, 0: "only" })).toEqual(["only"])
+    })
+
+    it("handles large collections", () => {
+        const mock: Record<string, unknown> = { Count: 100 }
+        for (let i = 0; i < 100; i++) {
+            mock[i] = i * 2
+        }
+        const result = toArray<number>(mock)
+        expect(result).toHaveLength(100)
+        expect(result[0]).toBe(0)
+        expect(result[50]).toBe(100)
+        expect(result[99]).toBe(198)
+    })
+})
+
+// ===========================================================================
+// useFrameSync — simple mode (no selector)
+// ===========================================================================
+
+describe("useFrameSync (simple mode)", () => {
+    let container: ReturnType<typeof createMockContainer>
+
+    beforeEach(() => {
+        container = createMockContainer()
+    })
+
+    afterEach(() => {
+        unmount(container as any)
+    })
+
+    function renderHookCapture<T>(
+        getter: () => T,
+        deps?: readonly unknown[]
+    ) {
+        let capturedValue: T = undefined as T
+        let renderCount = 0
+
+        function TestComponent() {
+            const value = useFrameSync(getter, deps)
+            capturedValue = value
+            renderCount++
+            return null
+        }
+
+        render(<TestComponent />, container as any)
+
+        return {
+            get value() { return capturedValue },
+            get renderCount() { return renderCount },
+        }
+    }
+
+    it("returns initial value from getter", async () => {
+        const capture = renderHookCapture(() => 42)
+        await flushMicrotasks()
+        expect(capture.value).toBe(42)
+    })
+
+    it("updates when primitive value changes", async () => {
+        let counter = 0
+        const capture = renderHookCapture(() => counter)
+        await flushMicrotasks()
+        await advanceFrame()
+        const initialRenders = capture.renderCount
+
+        counter = 1
+        await advanceFrame()
+        expect(capture.renderCount).toBeGreaterThan(initialRenders)
+        expect(capture.value).toBe(1)
+    })
+
+    it("does not re-render when value is unchanged", async () => {
+        const capture = renderHookCapture(() => "stable")
+        await flushMicrotasks()
+        await advanceFrame()
+        const initialRenders = capture.renderCount
+
+        await advanceFrame()
+        await advanceFrame()
+        expect(capture.renderCount).toBe(initialRenders)
+    })
+
+    it("handles null return from getter", async () => {
+        const capture = renderHookCapture(() => null)
+        await flushMicrotasks()
+        expect(capture.value).toBeNull()
+    })
+
+    it("handles getter that throws", async () => {
+        const capture = renderHookCapture(() => { throw new Error("boom") })
+        await flushMicrotasks()
+        expect(capture.value).toBeUndefined()
+    })
+
+    it("stops polling after unmount", async () => {
+        const getter = vi.fn(() => 42)
+        renderHookCapture(getter)
+        await flushMicrotasks()
+        await advanceFrame()
+
+        const callsBeforeUnmount = getter.mock.calls.length
+
+        unmount(container as any)
+        await flushMicrotasks()
+
+        await advanceFrame()
+        await advanceFrame()
+        await advanceFrame()
+
+        // At most one extra call from the in-flight RAF callback
+        expect(getter.mock.calls.length).toBeLessThanOrEqual(callsBeforeUnmount + 1)
+    })
+
+    it("uses Object.is for comparison (NaN === NaN)", async () => {
+        let val = NaN
+        const capture = renderHookCapture(() => val)
+        await flushMicrotasks()
+        await advanceFrame()
+        const initialRenders = capture.renderCount
+
+        // NaN should be Object.is equal to NaN — no re-render
+        val = NaN
+        await advanceFrame()
+        expect(capture.renderCount).toBe(initialRenders)
+    })
+})
+
+// ===========================================================================
+// useFrameSync — selector mode
+// ===========================================================================
+
+describe("useFrameSync (selector mode)", () => {
+    let container: ReturnType<typeof createMockContainer>
+
+    beforeEach(() => {
+        container = createMockContainer()
+    })
+
+    afterEach(() => {
+        unmount(container as any)
+    })
+
+    function renderHookCapture<T>(
+        getter: () => T,
+        select: (v: T) => readonly unknown[],
+        deps?: readonly unknown[]
+    ) {
+        let capturedValue: T = undefined as T
+        let renderCount = 0
+
+        function TestComponent() {
+            const value = useFrameSync(getter, select, deps)
+            capturedValue = value
+            renderCount++
+            return null
+        }
+
+        render(<TestComponent />, container as any)
+
+        return {
+            get value() { return capturedValue },
+            get renderCount() { return renderCount },
+        }
+    }
+
+    it("returns initial value from getter on first render", async () => {
+        const capture = renderHookCapture(
+            () => ({ name: "Town", population: 100 }),
+            (v) => [v.name, v.population]
+        )
+        await flushMicrotasks()
+
+        expect(capture.value).toEqual({ name: "Town", population: 100 })
+    })
+
+    it("returns null when getter returns null", async () => {
+        const capture = renderHookCapture(
+            () => null,
+            (v) => [v]
+        )
+        await flushMicrotasks()
+
+        expect(capture.value).toBeNull()
+    })
+
+    it("returns undefined when getter throws", async () => {
+        const capture = renderHookCapture(
+            () => { throw new Error("destroyed") },
+            (v) => [v]
+        )
+        await flushMicrotasks()
+
+        expect(capture.value).toBeUndefined()
+    })
+
+    it("re-renders when a selected dep changes", async () => {
+        const data = { name: "Town A", count: 1, untracked: "foo" }
+
+        const capture = renderHookCapture(
+            () => data,
+            (v) => [v.name, v.count]
+        )
+        await flushMicrotasks()
+        const initialRenders = capture.renderCount
+
+        // Advance one frame with no changes — should not re-render
+        await advanceFrame()
+        expect(capture.renderCount).toBe(initialRenders)
+
+        // Change a tracked dep
+        data.name = "Town B"
+        await advanceFrame()
+
+        expect(capture.renderCount).toBeGreaterThan(initialRenders)
+        expect(capture.value.name).toBe("Town B")
+    })
+
+    it("does not re-render when untracked properties change", async () => {
+        const data = { name: "Town", count: 1, untracked: "a" }
+
+        const capture = renderHookCapture(
+            () => data,
+            (v) => [v.name, v.count]
+        )
+        await flushMicrotasks()
+        // Let the effect run and schedule the first RAF check
+        await advanceFrame()
+        const afterInit = capture.renderCount
+
+        // Change only an untracked property
+        data.untracked = "b"
+        await advanceFrame()
+
+        expect(capture.renderCount).toBe(afterInit)
+    })
+
+    it("detects changes in the number of selected deps", async () => {
+        let depCount = 2
+
+        const capture = renderHookCapture(
+            () => "value",
+            () => {
+                // Return different-length arrays based on external state
+                const arr: unknown[] = []
+                for (let i = 0; i < depCount; i++) arr.push(i)
+                return arr
+            }
+        )
+        await flushMicrotasks()
+        await advanceFrame()
+        const afterInit = capture.renderCount
+
+        // Change the number of deps
+        depCount = 3
+        await advanceFrame()
+
+        expect(capture.renderCount).toBeGreaterThan(afterInit)
+    })
+
+    it("simulates C# proxy caching — same object reference, property changes", async () => {
+        // This is the core scenario: a C# proxy always returns the same
+        // JS object reference, but its properties change because they
+        // read through to C# on each access.
+        const proxy = { Name: "Village", NPCCount: 3, Version: 1 }
+
+        const capture = renderHookCapture(
+            () => proxy, // Always returns the SAME object reference
+            (p) => [p.Name, p.NPCCount, p.Version]
+        )
+        await flushMicrotasks()
+        await advanceFrame()
+        expect(capture.value.Name).toBe("Village")
+        const afterInit = capture.renderCount
+
+        // Mutate the proxy (simulates C# property change via proxy)
+        proxy.Name = "City"
+        proxy.Version = 2
+        await advanceFrame()
+
+        expect(capture.renderCount).toBeGreaterThan(afterInit)
+        expect(capture.value.Name).toBe("City")
+    })
+
+    it("handles nullable C# references with optional chaining in select", async () => {
+        let currentPlace: { Name: string; Items: { Count: number } } | null = {
+            Name: "Tavern",
+            Items: { Count: 5 },
+        }
+
+        const capture = renderHookCapture(
+            () => currentPlace,
+            (p) => [p?.Name, p?.Items?.Count]
+        )
+        await flushMicrotasks()
+        await advanceFrame()
+        expect(capture.value?.Name).toBe("Tavern")
+        const afterInit = capture.renderCount
+
+        // Set to null — should detect change (deps go from ["Tavern", 5] to [undefined, undefined])
+        currentPlace = null
+        await advanceFrame()
+
+        expect(capture.renderCount).toBeGreaterThan(afterInit)
+        expect(capture.value).toBeNull()
+    })
+
+    it("works with version stamp pattern", async () => {
+        const gameState = { Version: 1, data: "initial" }
+
+        const capture = renderHookCapture(
+            () => gameState,
+            (s) => [s.Version]
+        )
+        await flushMicrotasks()
+        await advanceFrame()
+        const afterInit = capture.renderCount
+
+        // No version change — no re-render
+        gameState.data = "changed but version same"
+        await advanceFrame()
+        expect(capture.renderCount).toBe(afterInit)
+
+        // Bump version — triggers re-render
+        gameState.Version = 2
+        gameState.data = "updated"
+        await advanceFrame()
+        expect(capture.renderCount).toBeGreaterThan(afterInit)
+        expect(capture.value.data).toBe("updated")
+    })
+
+    it("stops polling after unmount", async () => {
+        const getter = vi.fn(() => 42)
+
+        renderHookCapture(getter, (v) => [v])
+        await flushMicrotasks()
+        await advanceFrame()
+
+        const callsBeforeUnmount = getter.mock.calls.length
+
+        // Unmount
+        unmount(container as any)
+        await flushMicrotasks()
+
+        // Advance more frames — getter should not be called
+        await advanceFrame()
+        await advanceFrame()
+        await advanceFrame()
+
+        // At most one extra call from the in-flight RAF callback
+        expect(getter.mock.calls.length).toBeLessThanOrEqual(callsBeforeUnmount + 1)
+    })
+
+    it("continues polling across multiple frames", async () => {
+        const data = { value: 0 }
+
+        const capture = renderHookCapture(
+            () => data,
+            (d) => [d.value]
+        )
+        await flushMicrotasks()
+        await advanceFrame()
+        const afterInit = capture.renderCount
+
+        // Frame 2: change value
+        data.value = 1
+        await advanceFrame()
+        expect(capture.renderCount).toBeGreaterThan(afterInit)
+        const afterFirst = capture.renderCount
+
+        // Frame 3: change value again
+        data.value = 2
+        await advanceFrame()
+        expect(capture.renderCount).toBeGreaterThan(afterFirst)
+        expect(capture.value.value).toBe(2)
+    })
+
+    it("always returns fresh value from getter on render", async () => {
+        // Even between detected changes, the returned value should
+        // be the current live getter result (not a stale snapshot).
+        let callCount = 0
+        const capture = renderHookCapture(
+            () => {
+                callCount++
+                return { fresh: callCount }
+            },
+            () => [1] // Deps never change after init
+        )
+        await flushMicrotasks()
+
+        // The value should reflect a recent getter call
+        expect(capture.value.fresh).toBeGreaterThan(0)
+    })
+})
+
+// ===========================================================================
+// useFrameSyncWith (deprecated)
+// ===========================================================================
+
+describe("useFrameSyncWith (deprecated)", () => {
+    let container: ReturnType<typeof createMockContainer>
+
+    beforeEach(() => {
+        container = createMockContainer()
+    })
+
+    afterEach(() => {
+        unmount(container as any)
+    })
+
+    it("works with custom equality for new JS objects", async () => {
+        // useFrameSyncWith works when the getter returns a NEW object each time
+        // (not a cached proxy). This is its valid use case.
+        let x = 1, y = 2, z = 3
+        let capturedValue: { x: number; y: number; z: number } = undefined as any
+
+        function TestComponent() {
+            const value = useFrameSyncWith(
+                () => ({ x, y, z }),
+                (a, b) => a.x === b.x && a.y === b.y && a.z === b.z
+            )
+            capturedValue = value
+            return null
+        }
+
+        render(<TestComponent />, container as any)
+        await flushMicrotasks()
+        expect(capturedValue).toEqual({ x: 1, y: 2, z: 3 })
+
+        // No change — should not update (custom equality says they're equal)
+        await advanceFrame()
+        const stableValue = capturedValue
+
+        await advanceFrame()
+        // The reference may change (new object each getter call) but
+        // custom equality prevents unnecessary state updates
+        expect(capturedValue).toEqual({ x: 1, y: 2, z: 3 })
+
+        // Change a value — should trigger update
+        x = 10
+        await advanceFrame()
+        expect(capturedValue.x).toBe(10)
+    })
+})

package/src/hooks.ts

@@ -1,30 +1,65 @@
-import { useState, useEffect, useRef } from "react"
+import { useState, useEffect, useRef, useReducer } from "react"
 
 /**
  * Syncs a value from C# (or any external source) to React state, checking every frame.
  *
- * This hook eliminates the need for C# events or codegen - just read any property
- * and React will automatically update when it changes.
+ * Has two modes depending on whether a `select` function is provided:
+ *
+ * **Simple mode** (no selector): Compares values with `Object.is`. Best for primitives
+ * (numbers, strings, booleans) and cases where the getter returns a new object each time.
+ *
+ * **Selector mode**: Extracts an array of comparable values to watch. Re-renders only when
+ * any selected value changes. Essential for C# proxy objects where the proxy reference is
+ * cached — without a selector, you'd be comparing the same proxy to itself.
+ * The returned value is always read fresh from the getter during render.
  *
  * @param getter - Function that returns the current value (called every frame)
- * @param deps - Optional dependency array (if getter depends on changing references)
+ * @param selectOrDeps - Either a selector function or a dependency array
+ * @param deps - Optional dependency array (only when using a selector)
  * @returns The current value, updated each frame if changed
  *
  * @example
- * // Sync a C# property to React
- * const health = useFrameSync(() => player.health)
- * const position = useFrameSync(() => transform.position)
+ * // Simple: sync a C# property (primitives)
+ * const health = useFrameSync(() => player.Health)
+ * const score = useFrameSync(() => gameManager.Score)
+ *
+ * @example
+ * // Selector: watch specific properties on a C# proxy object
+ * const place = useFrameSync(
+ *     () => gameState.currentPlace,
+ *     (p) => [p?.Name, p?.NPCs?.Count, p?.Items?.Count]
+ * )
  *
  * @example
- * // With dependencies (if the object reference can change)
- * const health = useFrameSync(() => currentPlayer.health, [currentPlayer])
+ * // Selector: with a version stamp from C#
+ * const quest = useFrameSync(
+ *     () => questManager.activeQuest ?? null,
+ *     (q) => [q?.Version]
+ * )
  *
  * @example
- * // Derived values work too
- * const healthPercent = useFrameSync(() => player.health / player.maxHealth * 100)
+ * // Simple with dependencies (if the source reference can change)
+ * const health = useFrameSync(() => currentPlayer.Health, [currentPlayer])
  */
-export function useFrameSync<T>(getter: () => T, deps: readonly unknown[] = []): T {
-    // Safely get initial value
+export function useFrameSync<T>(
+    getter: () => T,
+    selectOrDeps?: ((value: T) => readonly unknown[]) | readonly unknown[],
+    deps?: readonly unknown[]
+): T {
+    // Determine which mode we're in
+    const hasSelector = typeof selectOrDeps === "function"
+    const select = hasSelector ? selectOrDeps as (value: T) => readonly unknown[] : undefined
+    const effectDeps = hasSelector ? (deps ?? []) : (selectOrDeps as readonly unknown[] ?? [])
+
+    if (select) {
+        return useFrameSyncSelect(getter, select, effectDeps)
+    } else {
+        return useFrameSyncSimple(getter, effectDeps)
+    }
+}
+
+/** Simple mode: compare with Object.is. */
+function useFrameSyncSimple<T>(getter: () => T, deps: readonly unknown[]): T {
     const getInitialValue = (): T => {
         try {
             return getter()
@@ -38,11 +73,9 @@ export function useFrameSync<T>(getter: () => T, deps: readonly unknown[] = []):
     const getterRef = useRef(getter)
     const runningRef = useRef(false)
 
-    // Keep getter ref updated
     getterRef.current = getter
 
     useEffect(() => {
-        // Re-initialize when deps change
         try {
             const initial = getterRef.current()
             lastValueRef.current = initial
@@ -81,20 +114,103 @@ export function useFrameSync<T>(getter: () => T, deps: readonly unknown[] = []):
     return value
 }
 
+/** Selector mode: extract comparable values, always return fresh from getter. */
+function useFrameSyncSelect<T>(
+    getter: () => T,
+    select: (value: T) => readonly unknown[],
+    deps: readonly unknown[]
+): T {
+    const [, forceRender] = useReducer((x: number) => x + 1, 0)
+    const getterRef = useRef(getter)
+    const selectRef = useRef(select)
+    const lastSelectedRef = useRef<readonly unknown[]>([])
+    const runningRef = useRef(false)
+    const initializedRef = useRef(false)
+
+    getterRef.current = getter
+    selectRef.current = select
+
+    // Initialize dependency tracking on first render
+    if (!initializedRef.current) {
+        initializedRef.current = true
+        try {
+            const val = getter()
+            lastSelectedRef.current = select(val)
+        } catch {
+            // Getter or select failed, keep empty deps
+        }
+    }
+
+    useEffect(() => {
+        try {
+            const val = getterRef.current()
+            lastSelectedRef.current = selectRef.current(val)
+        } catch {
+            // Getter or select failed
+        }
+
+        runningRef.current = true
+
+        const check = () => {
+            if (!runningRef.current) return
+
+            try {
+                const current = getterRef.current()
+                const selected = selectRef.current(current)
+                const prev = lastSelectedRef.current
+                const changed = selected.length !== prev.length ||
+                    selected.some((val, i) => !Object.is(val, prev[i]))
+
+                if (changed) {
+                    lastSelectedRef.current = selected
+                    forceRender()
+                }
+            } catch {
+                // Getter or select might fail if object was destroyed
+            }
+
+            if (runningRef.current) {
+                requestAnimationFrame(check)
+            }
+        }
+
+        requestAnimationFrame(check)
+
+        return () => {
+            runningRef.current = false
+        }
+    }, deps)
+
+    // Always read fresh from getter during render.
+    // This ensures we return the latest proxy with current C# state.
+    try {
+        return getterRef.current()
+    } catch {
+        return undefined as T
+    }
+}
+
 /**
- * Similar to useFrameSync but with a custom equality function.
- * Useful for objects/structs where reference equality isn't sufficient.
+ * @deprecated Use `useFrameSync` with a selector instead.
  *
- * @param getter - Function that returns the current value
- * @param isEqual - Custom equality function
- * @param deps - Optional dependency array
+ * `useFrameSyncWith` compares the value returned by the getter using a custom
+ * equality function. However, this does NOT work with C# proxy objects because
+ * the proxy reference is cached — you end up comparing the same object to itself.
  *
- * @example
- * // Sync a Vector3, comparing by value not reference
+ * Instead, use `useFrameSync` with a selector that extracts comparable values:
+ * ```ts
+ * // Before (broken with C# proxies):
  * const pos = useFrameSyncWith(
  *     () => transform.position,
  *     (a, b) => a.x === b.x && a.y === b.y && a.z === b.z
  * )
+ *
+ * // After (works correctly):
+ * const pos = useFrameSync(
+ *     () => transform.position,
+ *     (p) => [p.x, p.y, p.z]
+ * )
+ * ```
  */
 export function useFrameSyncWith<T>(
     getter: () => T,
@@ -214,3 +330,45 @@ export function useThrottledSync<T>(
 
     return value
 }
+
+/**
+ * Converts a C# collection (List<T>, array, etc.) to a JavaScript array.
+ *
+ * C# collections exposed through the OneJS proxy are not JS arrays — they
+ * lack .map(), .filter(), and other array methods. This utility converts
+ * them for use in React rendering.
+ *
+ * Supports objects with a `.Count` property (List<T>, IList) or a `.Length`
+ * property (C# arrays). Returns an empty array for null/undefined input.
+ *
+ * @param collection - A C# collection, or null/undefined
+ * @returns A JavaScript array containing the elements
+ *
+ * @example
+ * // Map over a C# List in JSX
+ * {toArray(inventory.Items).map(item => <ItemView key={item.Id} item={item} />)}
+ *
+ * @example
+ * // Convert a C# array
+ * const renderers = toArray(go.GetComponentsInChildren(CS.UnityEngine.Renderer))
+ *
+ * @example
+ * // Safe with null — returns []
+ * const npcs = toArray(currentPlace?.NPCs)
+ *
+ * @example
+ * // With explicit type parameter
+ * const items = toArray<Item>(questLog.ActiveQuests)
+ */
+export function toArray<T = unknown>(collection: unknown): T[] {
+    if (collection == null) return []
+    const col = collection as Record<string, unknown>
+    const len = typeof col.Count === "number" ? col.Count
+              : typeof col.Length === "number" ? col.Length
+              : 0
+    const result: T[] = []
+    for (let i = 0; i < len; i++) {
+        result.push((col as any)[i])
+    }
+    return result
+}

package/src/host-config.ts

@@ -12,12 +12,6 @@ declare function clearTimeout(id: number): void;
 
 declare const console: { log: (...args: unknown[]) => void; error: (...args: unknown[]) => void };
 
-// Native delegate callback helpers (from QuickJSBootstrap __csHelpers)
-declare const __csHelpers: {
-    createDelegateCallback(fn: Function): number;
-    freeDelegateCallback(handle: number): void;
-    [key: string]: unknown;
-};
 
 // Priority constants from react-reconciler/constants
 // These match React's internal lane priorities
@@ -156,8 +150,6 @@ export interface Instance {
     hasMixedContent?: boolean;
     // For vector drawing: track the current generateVisualContent callback
     visualContentCallback?: GenerateVisualContentCallback;
-    // Native callback handle for the above (used to free slot on replacement)
-    visualContentCallbackHandle?: number;
 }
 
 export type TextInstance = Instance; // For Label elements with text content
@@ -444,14 +436,6 @@ function untrackParent(child: CSObject) {
     }
 }
 
-// Free native callback handles tracked on an instance (prevents callback table leak)
-function cleanupCallbackHandles(instance: Instance) {
-    if (instance.visualContentCallbackHandle !== undefined) {
-        __csHelpers.freeDelegateCallback(instance.visualContentCallbackHandle);
-        instance.visualContentCallbackHandle = undefined;
-        instance.visualContentCallback = undefined;
-    }
-}
 
 // Apply event handlers
 function applyEvents(instance: Instance, props: BaseProps) {
@@ -486,27 +470,17 @@ function applyVisualContentCallback(instance: Instance, props: BaseProps) {
     if (callback !== existingCallback) {
         const element = instance.element as unknown as { generateVisualContent: GenerateVisualContentCallback | null };
 
-        // Free old native callback handle to prevent callback table leak
+        // Remove old callback if exists
         if (existingCallback) {
+            // Clear the delegate via C# interop
             element.generateVisualContent = null;
-            if (instance.visualContentCallbackHandle !== undefined) {
-                __csHelpers.freeDelegateCallback(instance.visualContentCallbackHandle);
-            }
-            instance.visualContentCallbackHandle = undefined;
         }
 
         // Add new callback if provided
         if (callback) {
-            // Register with argument wrapping and track the handle for cleanup
-            const handle = __csHelpers.createDelegateCallback(callback);
-            if (handle >= 0) {
-                instance.visualContentCallbackHandle = handle;
-                // Pass pre-resolved handle directly — bypasses __resolveValue's auto-registration
-                element.generateVisualContent = { __csCallbackHandle: handle } as any;
-            } else {
-                // WebGL path: no native callback table
-                element.generateVisualContent = callback;
-            }
+            // Assign callback to generateVisualContent property
+            // The C# interop layer handles the delegate conversion
+            element.generateVisualContent = callback;
             instance.visualContentCallback = callback;
         } else {
             instance.visualContentCallback = undefined;
@@ -975,7 +949,6 @@ export const hostConfig = {
             removeMergedTextChild(parentInstance, child);
         } else {
             __eventAPI.removeAllEventListeners(child.element);
-            cleanupCallbackHandles(child);
             parentInstance.element.Remove(child.element);
         }
         untrackParent(child.element);
@@ -983,7 +956,6 @@ export const hostConfig = {
 
     removeChildFromContainer(container: Container, child: Instance) {
         __eventAPI.removeAllEventListeners(child.element);
-        cleanupCallbackHandles(child);
         container.Remove(child.element);
         untrackParent(child.element);
     },

package/src/index.ts

@@ -38,8 +38,8 @@ export type {
 // Vector Drawing
 export { Transform2D, useVectorContent } from './vector';
 
-// Sync Hooks (C# interop)
-export { useFrameSync, useFrameSyncWith, useThrottledSync } from './hooks';
+// Sync Hooks & C# Interop Utilities
+export { useFrameSync, useFrameSyncWith, useThrottledSync, toArray } from './hooks';
 
 // Types
 export type {