onejs-react 0.1.9 → 0.1.11

package/package.json

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

package/src/__tests__/collection-sync.test.tsx

@@ -0,0 +1,436 @@
+/**
+ * End-to-end tests for collection state sync patterns.
+ *
+ * Simulates the real-world use case of syncing dynamic C# game state
+ * (inventories, quest logs, NPC lists) to React components using
+ * useFrameSync selector mode + toArray.
+ *
+ * Tests the parent/child pattern:
+ * - Parent watches list structure (Count) via selector
+ * - Child components each watch their own item properties via selector
+ * - When an item property changes, only that child re-renders
+ * - When items are added/removed, the parent re-renders
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
+import React from "react"
+import { useFrameSync, toArray } from "../hooks"
+import { render, unmount } from "../renderer"
+import { createMockContainer, flushMicrotasks } from "./mocks"
+
+// ---------------------------------------------------------------------------
+// RAF mock
+// ---------------------------------------------------------------------------
+
+type RafCallback = (time: number) => void
+
+let rafQueue: Array<{ id: number; callback: RafCallback }> = []
+let nextRafId = 0
+
+function flushRaf() {
+    const queue = [...rafQueue]
+    rafQueue = []
+    const now = Date.now()
+    for (const { callback } of queue) {
+        callback(now)
+    }
+}
+
+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
+})
+
+// ---------------------------------------------------------------------------
+// Mock C# proxy objects — simulates proxy caching behavior
+//
+// In real OneJS, accessing a C# object from JS always returns the same
+// proxy reference (cached by handle). Properties read through to C# on
+// each access, so mutations are visible through the same reference.
+// ---------------------------------------------------------------------------
+
+interface MockItem {
+    Id: number
+    Name: string
+    Durability: number
+    StackCount: number
+    Version: number
+}
+
+interface MockInventory {
+    Items: { Count: number; [index: number]: MockItem }
+}
+
+function createMockInventory(items: MockItem[]): MockInventory {
+    // Simulates a C# List<Item> — same proxy object, Count and indexer
+    // read live values (mutating the items array is visible immediately)
+    const proxy: any = {
+        get Count() { return items.length },
+    }
+    // Numeric indexer — proxy reads live from the array
+    return {
+        Items: new Proxy(proxy, {
+            get(target, prop) {
+                if (prop === "Count") return items.length
+                const idx = Number(prop)
+                if (!isNaN(idx) && idx >= 0 && idx < items.length) {
+                    return items[idx]
+                }
+                return target[prop]
+            }
+        })
+    }
+}
+
+function createMockItem(id: number, name: string, durability: number): MockItem {
+    return { Id: id, Name: name, Durability: durability, StackCount: 1, Version: 1 }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("collection sync: parent/child pattern", () => {
+    let container: ReturnType<typeof createMockContainer>
+
+    beforeEach(() => {
+        container = createMockContainer()
+    })
+
+    afterEach(() => {
+        unmount(container as any)
+    })
+
+    it("parent re-renders when items are added, children render per item", async () => {
+        const items: MockItem[] = [
+            createMockItem(1, "Sword", 100),
+            createMockItem(2, "Shield", 80),
+        ]
+        const inventory = createMockInventory(items)
+
+        let parentRenders = 0
+        const childRenders: Record<number, number> = {}
+
+        function ItemView({ item }: { item: MockItem }) {
+            const data = useFrameSync(
+                () => item,
+                (i) => [i.Name, i.Durability, i.StackCount]
+            )
+            childRenders[data.Id] = (childRenders[data.Id] || 0) + 1
+            return null
+        }
+
+        function InventoryList() {
+            const inv = useFrameSync(
+                () => inventory,
+                (i) => [i.Items.Count]
+            )
+            parentRenders++
+            return (
+                <>
+                    {toArray<MockItem>(inv.Items).map(item => (
+                        <ItemView key={item.Id} item={item} />
+                    ))}
+                </>
+            )
+        }
+
+        render(<InventoryList />, container as any)
+        await flushMicrotasks()
+        await advanceFrame()
+
+        expect(parentRenders).toBeGreaterThanOrEqual(1)
+        expect(childRenders[1]).toBeGreaterThanOrEqual(1)
+        expect(childRenders[2]).toBeGreaterThanOrEqual(1)
+
+        const parentRendersAfterInit = parentRenders
+        const child1RendersAfterInit = childRenders[1]
+        const child2RendersAfterInit = childRenders[2]
+
+        // Add a new item
+        items.push(createMockItem(3, "Potion", 1))
+        await advanceFrame()
+
+        // Parent should re-render (Count changed from 2 to 3)
+        expect(parentRenders).toBeGreaterThan(parentRendersAfterInit)
+        // New child should have rendered
+        expect(childRenders[3]).toBeGreaterThanOrEqual(1)
+    })
+
+    it("only the affected child re-renders when an item property changes", async () => {
+        const items: MockItem[] = [
+            createMockItem(1, "Sword", 100),
+            createMockItem(2, "Shield", 80),
+            createMockItem(3, "Potion", 1),
+        ]
+        const inventory = createMockInventory(items)
+
+        let parentRenders = 0
+        const childRenders: Record<number, number> = {}
+
+        function ItemView({ item }: { item: MockItem }) {
+            const data = useFrameSync(
+                () => item,
+                (i) => [i.Name, i.Durability, i.StackCount]
+            )
+            childRenders[data.Id] = (childRenders[data.Id] || 0) + 1
+            return null
+        }
+
+        function InventoryList() {
+            const inv = useFrameSync(
+                () => inventory,
+                (i) => [i.Items.Count]
+            )
+            parentRenders++
+            return (
+                <>
+                    {toArray<MockItem>(inv.Items).map(item => (
+                        <ItemView key={item.Id} item={item} />
+                    ))}
+                </>
+            )
+        }
+
+        render(<InventoryList />, container as any)
+        await flushMicrotasks()
+        await advanceFrame()
+
+        const parentRendersAfterInit = parentRenders
+        const child1After = childRenders[1]
+        const child2After = childRenders[2]
+        const child3After = childRenders[3]
+
+        // Change only Sword's durability (simulates using the item)
+        items[0].Durability = 90
+        await advanceFrame()
+
+        // Parent should NOT re-render (Count unchanged)
+        expect(parentRenders).toBe(parentRendersAfterInit)
+        // Only Sword's child should re-render
+        expect(childRenders[1]).toBeGreaterThan(child1After)
+        // Shield and Potion should NOT re-render
+        expect(childRenders[2]).toBe(child2After)
+        expect(childRenders[3]).toBe(child3After)
+    })
+
+    it("version stamp on items catches any property change", async () => {
+        const items: MockItem[] = [
+            createMockItem(1, "Sword", 100),
+            createMockItem(2, "Shield", 80),
+        ]
+        const inventory = createMockInventory(items)
+
+        const childRenders: Record<number, number> = {}
+
+        function ItemView({ item }: { item: MockItem }) {
+            // Watch only Version — catches all changes without listing every property
+            const data = useFrameSync(
+                () => item,
+                (i) => [i.Version]
+            )
+            childRenders[data.Id] = (childRenders[data.Id] || 0) + 1
+            return null
+        }
+
+        function InventoryList() {
+            const inv = useFrameSync(
+                () => inventory,
+                (i) => [i.Items.Count]
+            )
+            return (
+                <>
+                    {toArray<MockItem>(inv.Items).map(item => (
+                        <ItemView key={item.Id} item={item} />
+                    ))}
+                </>
+            )
+        }
+
+        render(<InventoryList />, container as any)
+        await flushMicrotasks()
+        await advanceFrame()
+
+        const child1After = childRenders[1]
+        const child2After = childRenders[2]
+
+        // Change Sword's durability AND bump its version (simulates Fody)
+        items[0].Durability = 90
+        items[0].Version = 2
+        await advanceFrame()
+
+        // Sword re-renders (version changed)
+        expect(childRenders[1]).toBeGreaterThan(child1After)
+        // Shield does NOT re-render (version unchanged)
+        expect(childRenders[2]).toBe(child2After)
+    })
+
+    it("handles item removal correctly", async () => {
+        const items: MockItem[] = [
+            createMockItem(1, "Sword", 100),
+            createMockItem(2, "Shield", 80),
+            createMockItem(3, "Potion", 1),
+        ]
+        const inventory = createMockInventory(items)
+
+        let parentRenders = 0
+        const childRenders: Record<number, number> = {}
+
+        function ItemView({ item }: { item: MockItem }) {
+            const data = useFrameSync(
+                () => item,
+                (i) => [i.Name, i.Durability]
+            )
+            childRenders[data.Id] = (childRenders[data.Id] || 0) + 1
+            return null
+        }
+
+        function InventoryList() {
+            const inv = useFrameSync(
+                () => inventory,
+                (i) => [i.Items.Count]
+            )
+            parentRenders++
+            return (
+                <>
+                    {toArray<MockItem>(inv.Items).map(item => (
+                        <ItemView key={item.Id} item={item} />
+                    ))}
+                </>
+            )
+        }
+
+        render(<InventoryList />, container as any)
+        await flushMicrotasks()
+        await advanceFrame()
+
+        const parentRendersAfterInit = parentRenders
+        expect(childRenders[1]).toBeGreaterThanOrEqual(1)
+        expect(childRenders[2]).toBeGreaterThanOrEqual(1)
+        expect(childRenders[3]).toBeGreaterThanOrEqual(1)
+
+        // Remove Shield (index 1)
+        items.splice(1, 1)
+        await advanceFrame()
+
+        // Parent should re-render (Count changed from 3 to 2)
+        expect(parentRenders).toBeGreaterThan(parentRendersAfterInit)
+    })
+
+    it("nullable parent with optional chaining works end-to-end", async () => {
+        let currentPlace: { Name: string; NPCs: { Count: number; [i: number]: { Name: string; Dialogue: string } } } | null = {
+            Name: "Tavern",
+            NPCs: {
+                Count: 2,
+                0: { Name: "Barkeep", Dialogue: "Welcome!" },
+                1: { Name: "Bard", Dialogue: "La la la~" },
+            },
+        }
+
+        let parentRenders = 0
+        const npcRenders: Record<string, number> = {}
+
+        function NPCView({ npc }: { npc: { Name: string; Dialogue: string } }) {
+            const data = useFrameSync(
+                () => npc,
+                (n) => [n.Name, n.Dialogue]
+            )
+            npcRenders[data.Name] = (npcRenders[data.Name] || 0) + 1
+            return null
+        }
+
+        function PlaceUI() {
+            const place = useFrameSync(
+                () => currentPlace,
+                (p) => [p?.Name, p?.NPCs?.Count]
+            )
+            parentRenders++
+
+            if (!place) return null
+
+            return (
+                <>
+                    {toArray<{ Name: string; Dialogue: string }>(place.NPCs).map((npc, i) => (
+                        <NPCView key={npc.Name} npc={npc} />
+                    ))}
+                </>
+            )
+        }
+
+        render(<PlaceUI />, container as any)
+        await flushMicrotasks()
+        await advanceFrame()
+
+        expect(parentRenders).toBeGreaterThanOrEqual(1)
+        expect(npcRenders["Barkeep"]).toBeGreaterThanOrEqual(1)
+        expect(npcRenders["Bard"]).toBeGreaterThanOrEqual(1)
+
+        const parentAfterInit = parentRenders
+        const barkeepAfter = npcRenders["Barkeep"]
+
+        // Change Barkeep's dialogue (NPC property change)
+        currentPlace!.NPCs[0].Dialogue = "What'll ya have?"
+        await advanceFrame()
+
+        // Parent should NOT re-render (Name and NPC Count unchanged)
+        expect(parentRenders).toBe(parentAfterInit)
+        // Only Barkeep should re-render
+        expect(npcRenders["Barkeep"]).toBeGreaterThan(barkeepAfter)
+
+        const parentAfterDialogue = parentRenders
+
+        // Player leaves the tavern (set to null)
+        currentPlace = null
+        await advanceFrame()
+
+        // Parent should re-render (place changed to null)
+        expect(parentRenders).toBeGreaterThan(parentAfterDialogue)
+    })
+
+    it("multiple property changes in one frame only cause one re-render", async () => {
+        const item = createMockItem(1, "Sword", 100)
+
+        let renderCount = 0
+
+        function ItemView() {
+            const data = useFrameSync(
+                () => item,
+                (i) => [i.Name, i.Durability, i.StackCount, i.Version]
+            )
+            renderCount++
+            return null
+        }
+
+        render(<ItemView />, container as any)
+        await flushMicrotasks()
+        await advanceFrame()
+        const afterInit = renderCount
+
+        // Change multiple properties at once (between frames)
+        item.Name = "Broken Sword"
+        item.Durability = 0
+        item.Version = 2
+        await advanceFrame()
+
+        // Should only re-render once for all changes in the same frame
+        expect(renderCount).toBe(afterInit + 1)
+    })
+})

package/src/__tests__/components.test.tsx

@@ -20,8 +20,9 @@ import {
     Slider,
     ScrollView,
     Image,
+    clearImageCache,
 } from '../components';
-import { MockVisualElement, MockLength, MockColor, createMockContainer, flushMicrotasks, getEventAPI } from './mocks';
+import { MockVisualElement, MockTexture2D, MockLength, MockColor, createMockContainer, flushMicrotasks, getEventAPI, mockFileSystem } from './mocks';
 
 // Helper to extract value from style (handles both raw values and MockLength/MockColor)
 function getStyleValue(style: unknown): unknown {
@@ -58,7 +59,9 @@ describe('components', () => {
             const el = container.children[0] as MockVisualElement;
             expect(getStyleValue(el.style.width)).toBe(200);
             expect(getStyleValue(el.style.height)).toBe(100);
-            expect(el.style.flexDirection).toBe('row');
+            // flexDirection 'row' is converted to the Unity enum value FlexDirection.Row
+            const FlexDirection = (globalThis as any).CS.UnityEngine.UIElements.FlexDirection;
+            expect(el.style.flexDirection).toBe(FlexDirection.Row);
             expect(getStyleValue(el.style.paddingTop)).toBe(10);
         });
 
@@ -363,6 +366,83 @@ describe('components', () => {
             expect(getStyleValue(el.style.width)).toBe(100);
             expect(getStyleValue(el.style.height)).toBe(100);
         });
+
+        it('loads texture when src is provided', async () => {
+            mockFileSystem.set("/project/App/assets/images/logo.png", [0x89, 0x50, 0x4e, 0x47]);
+            (globalThis as any).__workingDir = "/project/App";
+
+            const container = createMockContainer();
+            render(<Image src="images/logo.png" style={{ width: 64, height: 64 }} />, container as any);
+            await flushMicrotasks();
+
+            const el = container.children[0] as any;
+            expect(el.image).toBeInstanceOf(MockTexture2D);
+            expect((el.image as MockTexture2D)._loaded).toBe(true);
+        });
+
+        it('returns null for missing file with console.error', async () => {
+            (globalThis as any).__workingDir = "/project/App";
+
+            const container = createMockContainer();
+            render(<Image src="images/missing.png" />, container as any);
+            await flushMicrotasks();
+
+            const el = container.children[0] as any;
+            expect(el.image).toBeNull();
+            expect(console.error).toHaveBeenCalledWith(
+                expect.stringContaining("Image src not found: images/missing.png")
+            );
+        });
+
+        it('caches textures across renders', async () => {
+            mockFileSystem.set("/project/App/assets/photos/hero.png", [0x89, 0x50]);
+            (globalThis as any).__workingDir = "/project/App";
+            const cs = (globalThis as any).CS;
+            const readSpy = vi.spyOn(cs.System.IO.File, 'ReadAllBytes');
+
+            const container = createMockContainer();
+            render(<Image src="photos/hero.png" />, container as any);
+            await flushMicrotasks();
+
+            // Re-render with same src
+            render(<Image src="photos/hero.png" />, container as any);
+            await flushMicrotasks();
+
+            expect(readSpy).toHaveBeenCalledTimes(1);
+        });
+
+        it('src takes precedence over image prop', async () => {
+            mockFileSystem.set("/project/App/assets/a.png", [0x89]);
+            (globalThis as any).__workingDir = "/project/App";
+            const manualTex = { manual: true };
+
+            const container = createMockContainer();
+            render(<Image src="a.png" image={manualTex} />, container as any);
+            await flushMicrotasks();
+
+            const el = container.children[0] as any;
+            expect(el.image).toBeInstanceOf(MockTexture2D);
+        });
+
+        it('clearImageCache resets the cache', async () => {
+            mockFileSystem.set("/project/App/assets/b.png", [0x89]);
+            (globalThis as any).__workingDir = "/project/App";
+            const cs = (globalThis as any).CS;
+            const readSpy = vi.spyOn(cs.System.IO.File, 'ReadAllBytes');
+
+            const container1 = createMockContainer();
+            render(<Image src="b.png" />, container1 as any);
+            await flushMicrotasks();
+
+            clearImageCache();
+
+            // Render in a new container to force a fresh component mount
+            const container2 = createMockContainer();
+            render(<Image src="b.png" />, container2 as any);
+            await flushMicrotasks();
+
+            expect(readSpy).toHaveBeenCalledTimes(2);
+        });
     });
 
     describe('event handler mapping', () => {

package/src/__tests__/host-config.test.ts

@@ -663,21 +663,23 @@ describe('host-config', () => {
     });
 
     describe('visibility', () => {
-        it('hideInstance sets display to none', () => {
+        it('hideInstance sets display to DisplayStyle.None', () => {
             const instance = createInstance('ojs-view', {});
 
             hideInstance(instance);
 
-            expect(instance.element.style.display).toBe('none');
+            const DisplayStyle = (globalThis as any).CS.UnityEngine.UIElements.DisplayStyle;
+            expect(instance.element.style.display).toBe(DisplayStyle.None);
         });
 
-        it('unhideInstance clears display', () => {
+        it('unhideInstance sets display to DisplayStyle.Flex', () => {
             const instance = createInstance('ojs-view', {});
-            instance.element.style.display = 'none';
+            const DisplayStyle = (globalThis as any).CS.UnityEngine.UIElements.DisplayStyle;
+            instance.element.style.display = DisplayStyle.None;
 
             unhideInstance(instance, {});
 
-            expect(instance.element.style.display).toBe('');
+            expect(instance.element.style.display).toBe(DisplayStyle.Flex);
         });
     });
 

package/src/__tests__/mocks.ts

@@ -223,14 +223,64 @@ export class MockImage extends MockVisualElement {
     }
 }
 
+/**
+ * Mock Texture2D for image loading tests
+ */
+export class MockTexture2D {
+    width: number
+    height: number
+    filterMode: number = 0
+    _loaded = false
+
+    constructor(w: number, h: number) {
+        this.width = w
+        this.height = h
+    }
+
+    LoadImage(_bytes: any): boolean {
+        this._loaded = true
+        return true
+    }
+}
+
+/**
+ * Mock file system for image loading tests.
+ * Tests can add entries to control which files "exist" and what bytes they contain.
+ */
+export const mockFileSystem = new Map<string, number[]>()
+
 /**
  * Create the mock CS global object that mirrors QuickJSBootstrap.js proxy
+ *
+ * Enum values match Unity's actual enum definitions so that tests
+ * verify the real mapping behavior (CSS string -> Unity enum number).
  */
 export function createMockCS() {
     return {
+        System: {
+            IO: {
+                Path: {
+                    Combine: (...parts: string[]) => parts.join("/"),
+                    GetDirectoryName: (p: string) => p.substring(0, p.lastIndexOf("/")),
+                },
+                File: {
+                    Exists: (path: string) => mockFileSystem.has(path),
+                    ReadAllBytes: (path: string) => mockFileSystem.get(path) || [],
+                },
+            },
+        },
         UnityEngine: {
             // Core types
             Color: MockColor,
+            Rect: class { constructor(public x: number, public y: number, public width: number, public height: number) {} },
+            ScaleMode: { StretchToFill: 0, ScaleAndCrop: 1, ScaleToFit: 2 },
+            Application: {
+                isEditor: true,
+                dataPath: "/project/Assets",
+                streamingAssetsPath: "/project/Assets/StreamingAssets",
+            },
+            Texture2D: MockTexture2D,
+            FilterMode: { Point: 0, Bilinear: 1, Trilinear: 2 },
             // UI Elements
             UIElements: {
                 VisualElement: MockVisualElement,
@@ -246,6 +296,39 @@ export function createMockCS() {
                 Length: MockLength,
                 LengthUnit: MockLengthUnit,
                 StyleKeyword: MockStyleKeyword,
+                // Enums (values match Unity's actual enum definitions)
+                FlexDirection: { Column: 0, ColumnReverse: 1, Row: 2, RowReverse: 3 },
+                Wrap: { NoWrap: 0, Wrap: 1, WrapReverse: 2 },
+                Align: { Auto: 0, FlexStart: 1, Center: 2, FlexEnd: 3, Stretch: 4 },
+                Justify: { FlexStart: 0, Center: 1, FlexEnd: 2, SpaceBetween: 3, SpaceAround: 4 },
+                Position: { Relative: 0, Absolute: 1 },
+                Overflow: { Visible: 0, Hidden: 1 },
+                DisplayStyle: { Flex: 0, None: 1 },
+                Visibility: { Visible: 0, Hidden: 1 },
+                WhiteSpace: { Normal: 0, NoWrap: 1 },
+                TextOverflow: { Clip: 0, Ellipsis: 1 },
+                TextOverflowPosition: { End: 0, Start: 1, Middle: 2 },
+                OverflowClipBox: { PaddingBox: 0, ContentBox: 1 },
+                PickingMode: { Position: 0, Ignore: 1 },
+                SliderDirection: { Horizontal: 0, Vertical: 1 },
+                // ScrollView enums
+                ScrollViewMode: { Vertical: 0, Horizontal: 1, VerticalAndHorizontal: 2 },
+                ScrollerVisibility: { Auto: 0, AlwaysVisible: 1, Hidden: 2 },
+                TouchScrollBehavior: { Unrestricted: 0, Elastic: 1, Clamped: 2 },
+                NestedInteractionKind: { Default: 0, StopScrolling: 1, ForwardScrolling: 2 },
+                // ListView enums
+                SelectionType: { None: 0, Single: 1, Multiple: 2 },
+                ListViewReorderMode: { Simple: 0, Animated: 1 },
+                AlternatingRowBackground: { None: 0, ContentOnly: 1, All: 2 },
+                CollectionVirtualizationMethod: { FixedHeight: 0, DynamicHeight: 1 },
+            },
+        },
+        OneJS: {
+            GPU: {
+                GPUBridge: {
+                    SetElementBackgroundImage: () => {},
+                    ClearElementBackgroundImage: () => {},
+                },
             },
         },
     };
@@ -270,6 +353,7 @@ export function findElementByHandle(handle: number): MockVisualElement | undefin
  */
 export function resetAllMocks(): void {
     createdElements = [];
+    mockFileSystem.clear();
 }
 
 /**
@@ -323,5 +407,7 @@ export function getEventAPI() {
         addEventListener: ReturnType<typeof import('vitest').vi.fn>;
         removeEventListener: ReturnType<typeof import('vitest').vi.fn>;
         removeAllEventListeners: ReturnType<typeof import('vitest').vi.fn>;
+        setParent: ReturnType<typeof import('vitest').vi.fn>;
+        removeParent: ReturnType<typeof import('vitest').vi.fn>;
     };
 }

package/src/__tests__/pre-setup.ts

@@ -0,0 +1,15 @@
+/**
+ * Pre-setup - Defines globals that must exist before any module imports.
+ *
+ * This runs before setup.ts to ensure useExtensions and CS are available when
+ * components.tsx is first imported (it calls useExtensions at module level).
+ * setup.ts replaces CS with a full mock in beforeEach.
+ */
+
+import { createMockCS } from "./mocks";
+
+// No-op useExtensions for test environment (extension methods are mocked directly on types)
+(globalThis as any).useExtensions = () => {};
+
+// Minimal CS mock so module-level code can reference CS.UnityEngine.ImageConversion
+(globalThis as any).CS = createMockCS();

package/src/__tests__/setup.ts

@@ -10,16 +10,17 @@
 
 import { vi, beforeEach, afterEach } from "vitest";
 import { createMockCS, resetAllMocks } from "./mocks";
+import { clearImageCache } from "../components";
 
 // Extend globalThis type for our mocks
 declare global {
-    // eslint-disable-next-line no-var
-    var CS: ReturnType<typeof createMockCS>;
     // eslint-disable-next-line no-var
     var __eventAPI: {
         addEventListener: ReturnType<typeof vi.fn>;
         removeEventListener: ReturnType<typeof vi.fn>;
         removeAllEventListeners: ReturnType<typeof vi.fn>;
+        setParent: ReturnType<typeof vi.fn>;
+        removeParent: ReturnType<typeof vi.fn>;
     };
 }
 
@@ -31,15 +32,18 @@ const originalQueueMicrotask = global.queueMicrotask;
 // Set up globals before each test
 beforeEach(() => {
     resetAllMocks();
+    clearImageCache();
 
     // Create fresh mock CS global
-    global.CS = createMockCS();
+    (globalThis as any).CS = createMockCS();
 
     // Mock event API with spies
     global.__eventAPI = {
         addEventListener: vi.fn(),
         removeEventListener: vi.fn(),
         removeAllEventListeners: vi.fn(),
+        setParent: vi.fn(),
+        removeParent: vi.fn(),
     };
 
     // Use real console but spy on it for test assertions

package/src/__tests__/style-parser.test.ts

@@ -303,10 +303,12 @@ describe("style-parser", () => {
             expect(parseStyleValue("flexShrink", 0)).toBe(0)
         })
 
-        it("passes through enum properties unchanged", () => {
-            expect(parseStyleValue("flexDirection", "row")).toBe("row")
-            expect(parseStyleValue("display", "none")).toBe("none")
-            expect(parseStyleValue("position", "absolute")).toBe("absolute")
+        it("converts enum properties to Unity enum values", () => {
+            const CS = (globalThis as any).CS
+            const UIE = CS.UnityEngine.UIElements
+            expect(parseStyleValue("flexDirection", "row")).toBe(UIE.FlexDirection.Row)
+            expect(parseStyleValue("display", "none")).toBe(UIE.DisplayStyle.None)
+            expect(parseStyleValue("position", "absolute")).toBe(UIE.Position.Absolute)
         })
 
         it("passes through unknown properties unchanged", () => {

package/src/components.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, type ReactElement, type Ref } from 'react';
+import { forwardRef, useMemo, type ReactElement, type Ref } from 'react';
 import type {
   ViewProps,
   TextProps,
@@ -21,6 +21,52 @@ import type {
   ImageElement,
 } from './types';
 
+declare const CS: any
+declare function useExtensions(typeRef: any): void
+
+// Register ImageConversion extension methods so tex.LoadImage(bytes) works
+useExtensions(CS.UnityEngine.ImageConversion)
+
+// Module-level texture cache shared across all Image instances
+const _textureCache = new Map<string, any>()
+
+function _resolveAssetPath(src: string): string {
+    const Path = CS.System.IO.Path
+    if (CS.UnityEngine.Application.isEditor) {
+        const workingDir = typeof (globalThis as any).__workingDir === "string"
+            ? (globalThis as any).__workingDir
+            : Path.Combine(Path.GetDirectoryName(CS.UnityEngine.Application.dataPath), "App")
+        return Path.Combine(workingDir, "assets", src)
+    }
+    return Path.Combine(CS.UnityEngine.Application.streamingAssetsPath, "onejs", "assets", src)
+}
+
+function _loadTexture(src: string): any | null {
+    const cached = _textureCache.get(src)
+    if (cached) return cached
+
+    const fullPath = _resolveAssetPath(src)
+    if (!CS.System.IO.File.Exists(fullPath)) {
+        console.error(`Image src not found: ${src} (resolved to ${fullPath})`)
+        return null
+    }
+
+    const bytes = CS.System.IO.File.ReadAllBytes(fullPath)
+    const tex = new CS.UnityEngine.Texture2D(2, 2)
+    tex.LoadImage(bytes)
+    tex.filterMode = CS.UnityEngine.FilterMode.Bilinear
+    _textureCache.set(src, tex)
+    return tex
+}
+
+/**
+ * Clear the Image component's texture cache.
+ * Call this if you need to force-reload images (e.g., after replacing files on disk).
+ */
+export function clearImageCache(): void {
+    _textureCache.clear()
+}
+
 // Props with ref support for intrinsic elements
 type WithRef<Props, Element> = Props & { ref?: Ref<Element> };
 
@@ -105,8 +151,12 @@ export const ScrollView = forwardRef<ScrollViewElement, ScrollViewProps>((props,
 });
 ScrollView.displayName = 'ScrollView';
 
-export const Image = forwardRef<ImageElement, ImageProps>((props, ref) => {
-  return <ojs-image ref={ref} {...props} />;
+export const Image = forwardRef<ImageElement, ImageProps>(({ src, image, ...rest }, ref) => {
+  const resolvedImage = useMemo(() => {
+    if (src) return _loadTexture(src)
+    return image
+  }, [src, image])
+  return <ojs-image ref={ref} image={resolvedImage} {...rest} />;
 });
 Image.displayName = 'Image';
 

package/src/hooks.ts

@@ -1,5 +1,9 @@
 import { useState, useEffect, useRef, useReducer } from "react"
 
+// QuickJS environment declarations
+declare function requestAnimationFrame(callback: (time: number) => void): number;
+declare function cancelAnimationFrame(id: number): void;
+
 /**
  * Syncs a value from C# (or any external source) to React state, checking every frame.
  *

package/src/host-config.ts

@@ -56,7 +56,10 @@ declare const CS: {
             CollectionVirtualizationMethod: CSEnum;
             DisplayStyle: CSEnum;
             PickingMode: CSEnum;
+            SliderDirection: CSEnum;
         };
+        ScaleMode: CSEnum;
+        Rect: new (...args: any[]) => any;
     };
     OneJS: {
         GPU: {
@@ -578,9 +581,10 @@ function removeMergedTextChild(parentInstance: Instance, child: Instance) {
 
 // Apply common props (text, value, label)
 function applyCommonProps(element: CSObject, props: Record<string, unknown>) {
-    if (props.text !== undefined) (element as { text: string }).text = props.text as string;
-    if (props.value !== undefined) (element as { value: unknown }).value = props.value;
-    if (props.label !== undefined) (element as { label: string }).label = props.label as string;
+    const el = element as any;
+    if (props.text !== undefined) el.text = props.text as string;
+    if (props.value !== undefined) el.value = props.value;
+    if (props.label !== undefined) el.label = props.label as string;
 }
 
 // Helper to set enum prop if defined
@@ -599,106 +603,62 @@ function setValueProp<T>(target: T, key: keyof T, props: Record<string, unknown>
 
 // Apply TextField-specific properties
 function applyTextFieldProps(element: CSObject, props: Record<string, unknown>) {
-    // Map readOnly prop to isReadOnly property
-    if (props.readOnly !== undefined) {
-        (element as { isReadOnly: boolean }).isReadOnly = props.readOnly as boolean;
-    }
-    if (props.multiline !== undefined) {
-        (element as { multiline: boolean }).multiline = props.multiline as boolean;
-    }
-    if (props.maxLength !== undefined) {
-        (element as { maxLength: number }).maxLength = props.maxLength as number;
-    }
-    if (props.isPasswordField !== undefined) {
-        (element as { isPasswordField: boolean }).isPasswordField = props.isPasswordField as boolean;
-    }
-    if (props.maskChar !== undefined) {
-        (element as { maskChar: string }).maskChar = (props.maskChar as string).charAt(0);
-    }
-    if (props.isDelayed !== undefined) {
-        (element as { isDelayed: boolean }).isDelayed = props.isDelayed as boolean;
-    }
-    if (props.selectAllOnFocus !== undefined) {
-        (element as { selectAllOnFocus: boolean }).selectAllOnFocus = props.selectAllOnFocus as boolean;
-    }
-    if (props.selectAllOnMouseUp !== undefined) {
-        (element as { selectAllOnMouseUp: boolean }).selectAllOnMouseUp = props.selectAllOnMouseUp as boolean;
-    }
-    if (props.hideMobileInput !== undefined) {
-        (element as { hideMobileInput: boolean }).hideMobileInput = props.hideMobileInput as boolean;
-    }
-    if (props.autoCorrection !== undefined) {
-        (element as { autoCorrection: boolean }).autoCorrection = props.autoCorrection as boolean;
-    }
+    const el = element as any;
+    if (props.readOnly !== undefined) el.isReadOnly = props.readOnly;
+    if (props.multiline !== undefined) el.multiline = props.multiline;
+    if (props.maxLength !== undefined) el.maxLength = props.maxLength;
+    if (props.isPasswordField !== undefined) el.isPasswordField = props.isPasswordField;
+    if (props.maskChar !== undefined) el.maskChar = (props.maskChar as string).charAt(0);
+    if (props.isDelayed !== undefined) el.isDelayed = props.isDelayed;
+    if (props.selectAllOnFocus !== undefined) el.selectAllOnFocus = props.selectAllOnFocus;
+    if (props.selectAllOnMouseUp !== undefined) el.selectAllOnMouseUp = props.selectAllOnMouseUp;
+    if (props.hideMobileInput !== undefined) el.hideMobileInput = props.hideMobileInput;
+    if (props.autoCorrection !== undefined) el.autoCorrection = props.autoCorrection;
     // Note: placeholder is handled differently in Unity - it's set via the textEdition interface
     // For now we skip it as it requires more complex handling
 }
 
 // Apply Slider-specific properties
 function applySliderProps(element: CSObject, props: Record<string, unknown>) {
-    if (props.lowValue !== undefined) {
-        (element as { lowValue: number }).lowValue = props.lowValue as number;
-    }
-    if (props.highValue !== undefined) {
-        (element as { highValue: number }).highValue = props.highValue as number;
-    }
-    if (props.showInputField !== undefined) {
-        (element as { showInputField: boolean }).showInputField = props.showInputField as boolean;
-    }
-    if (props.inverted !== undefined) {
-        (element as { inverted: boolean }).inverted = props.inverted as boolean;
-    }
-    if (props.pageSize !== undefined) {
-        (element as { pageSize: number }).pageSize = props.pageSize as number;
-    }
-    if (props.fill !== undefined) {
-        (element as { fill: boolean }).fill = props.fill as boolean;
-    }
+    const el = element as any;
+    if (props.lowValue !== undefined) el.lowValue = props.lowValue;
+    if (props.highValue !== undefined) el.highValue = props.highValue;
+    if (props.showInputField !== undefined) el.showInputField = props.showInputField;
+    if (props.inverted !== undefined) el.inverted = props.inverted;
+    if (props.pageSize !== undefined) el.pageSize = props.pageSize;
+    if (props.fill !== undefined) el.fill = props.fill;
     if (props.direction !== undefined) {
-        const UIE = CS.UnityEngine.UIElements;
-        (element as { direction: unknown }).direction = UIE.SliderDirection[props.direction as string];
+        el.direction = CS.UnityEngine.UIElements.SliderDirection[props.direction as string];
     }
 }
 
 // Apply Toggle-specific properties
 function applyToggleProps(element: CSObject, props: Record<string, unknown>) {
-    if (props.text !== undefined) {
-        (element as { text: string }).text = props.text as string;
-    }
-    if (props.toggleOnLabelClick !== undefined) {
-        (element as { toggleOnLabelClick: boolean }).toggleOnLabelClick = props.toggleOnLabelClick as boolean;
-    }
+    const el = element as any;
+    if (props.text !== undefined) el.text = props.text;
+    if (props.toggleOnLabelClick !== undefined) el.toggleOnLabelClick = props.toggleOnLabelClick;
 }
 
 // Apply Image-specific properties
 function applyImageProps(element: CSObject, props: Record<string, unknown>) {
-    if (props.image !== undefined) {
-        (element as { image: unknown }).image = props.image;
-    }
-    if (props.sprite !== undefined) {
-        (element as { sprite: unknown }).sprite = props.sprite;
-    }
-    if (props.vectorImage !== undefined) {
-        (element as { vectorImage: unknown }).vectorImage = props.vectorImage;
-    }
+    const el = element as any;
+    if (props.image !== undefined) el.image = props.image;
+    if (props.sprite !== undefined) el.sprite = props.sprite;
+    if (props.vectorImage !== undefined) el.vectorImage = props.vectorImage;
     if (props.scaleMode !== undefined) {
-        const scaleMode = CS.UnityEngine.ScaleMode[props.scaleMode as string];
-        (element as { scaleMode: unknown }).scaleMode = scaleMode;
+        el.scaleMode = CS.UnityEngine.ScaleMode[props.scaleMode as string];
     }
     if (props.tintColor !== undefined) {
-        // Parse color string to Unity Color
         const color = parseColor(props.tintColor as string);
-        if (color) {
-            (element as { tintColor: unknown }).tintColor = color;
-        }
+        if (color) el.tintColor = color;
     }
     if (props.sourceRect !== undefined) {
         const rect = props.sourceRect as { x: number; y: number; width: number; height: number };
-        (element as { sourceRect: unknown }).sourceRect = new CS.UnityEngine.Rect(rect.x, rect.y, rect.width, rect.height);
+        el.sourceRect = new CS.UnityEngine.Rect(rect.x, rect.y, rect.width, rect.height);
     }
     if (props.uv !== undefined) {
         const rect = props.uv as { x: number; y: number; width: number; height: number };
-        (element as { uv: unknown }).uv = new CS.UnityEngine.Rect(rect.x, rect.y, rect.width, rect.height);
+        el.uv = new CS.UnityEngine.Rect(rect.x, rect.y, rect.width, rect.height);
     }
 }
 

package/src/index.ts

@@ -10,6 +10,7 @@ export {
   ScrollView,
   Image,
   ListView,
+  clearImageCache,
 } from './components';
 
 // Renderer

package/src/style-parser.ts

@@ -9,11 +9,21 @@
 declare const CS: {
     UnityEngine: {
         Color: new (r: number, g: number, b: number, a: number) => CSColor;
+        Vector3: new (x: number, y: number, z: number) => any;
         FontStyle: Record<string, number>;
         UIElements: {
             Length: new (value: number, unit?: number) => CSLength;
             LengthUnit: { Pixel: number; Percent: number };
             StyleKeyword: { Auto: number; None: number; Initial: number };
+            Angle: { Degrees: (v: number) => any; Radians: (v: number) => any; Turns: (v: number) => any; Gradians: (v: number) => any };
+            Translate: new (x: any, y: any) => any;
+            Rotate: new (angle: any) => any;
+            Scale: new (v: any) => any;
+            TransformOrigin: new (x: any, y: any) => any;
+            StyleTranslate: new (v: any) => any;
+            StyleRotate: new (v: any) => any;
+            StyleScale: new (v: any) => any;
+            StyleTransformOrigin: new (v: any) => any;
             // Enums for style properties
             FlexDirection: Record<string, number>;
             Wrap: Record<string, number>;
@@ -357,6 +367,130 @@ export function parseColor(value: string): CSColor | null {
     return null
 }
 
+/**
+ * Parse a length value for transform properties (no keyword support)
+ * number → Length(n, Pixel), "50%" → Length(50, Percent), "10px" → Length(10, Pixel)
+ */
+function parseLengthForTransform(value: number | string): CSLength | null {
+    if (typeof value === "number") {
+        return new CS.UnityEngine.UIElements.Length(value, CS.UnityEngine.UIElements.LengthUnit.Pixel)
+    }
+    if (typeof value === "string") {
+        const match = value.trim().match(/^(-?[\d.]+)(px|%)?$/)
+        if (match) {
+            const num = parseFloat(match[1])
+            if (isNaN(num)) return null
+            const unit = match[2] === "%"
+                ? CS.UnityEngine.UIElements.LengthUnit.Percent
+                : CS.UnityEngine.UIElements.LengthUnit.Pixel
+            return new CS.UnityEngine.UIElements.Length(num, unit)
+        }
+    }
+    return null
+}
+
+/**
+ * Parse an angle value
+ * number → Angle.Degrees(n), string → parse unit suffix (deg|rad|turn|grad)
+ */
+function parseAngle(value: number | string): any | null {
+    const Angle = CS.UnityEngine.UIElements.Angle
+    if (typeof value === "number") {
+        return Angle.Degrees(value)
+    }
+    if (typeof value === "string") {
+        const match = value.trim().match(/^(-?[\d.]+)(deg|rad|turn|grad)?$/)
+        if (match) {
+            const num = parseFloat(match[1])
+            if (isNaN(num)) return null
+            const unit = match[2] || "deg"
+            if (unit === "rad") return Angle.Radians(num)
+            if (unit === "turn") return Angle.Turns(num)
+            if (unit === "grad") return Angle.Gradians(num)
+            return Angle.Degrees(num)
+        }
+    }
+    return null
+}
+
+/**
+ * Parse translate style: [x, y] array or C# Translate pass-through
+ */
+function parseTranslateStyle(value: unknown): unknown {
+    if (Array.isArray(value)) {
+        const x = parseLengthForTransform(value[0])
+        const y = parseLengthForTransform(value[1])
+        if (x !== null && y !== null) {
+            return new CS.UnityEngine.UIElements.StyleTranslate(
+                new CS.UnityEngine.UIElements.Translate(x, y)
+            )
+        }
+    }
+    if (typeof value === "object" && value !== null) {
+        try { return new CS.UnityEngine.UIElements.StyleTranslate(value) } catch { return value }
+    }
+    return value
+}
+
+/**
+ * Parse rotate style: number (degrees), string with unit, or C# Rotate pass-through
+ */
+function parseRotateStyle(value: unknown): unknown {
+    if (typeof value === "number" || typeof value === "string") {
+        const angle = parseAngle(value)
+        if (angle !== null) {
+            return new CS.UnityEngine.UIElements.StyleRotate(
+                new CS.UnityEngine.UIElements.Rotate(angle)
+            )
+        }
+    }
+    if (typeof value === "object" && value !== null) {
+        try { return new CS.UnityEngine.UIElements.StyleRotate(value) } catch { return value }
+    }
+    return value
+}
+
+/**
+ * Parse scale style: number (uniform), [x, y] array, or C# Scale pass-through
+ */
+function parseScaleStyle(value: unknown): unknown {
+    if (typeof value === "number") {
+        return new CS.UnityEngine.UIElements.StyleScale(
+            new CS.UnityEngine.UIElements.Scale(new CS.UnityEngine.Vector3(value, value, 1))
+        )
+    }
+    if (Array.isArray(value)) {
+        const x = typeof value[0] === "number" ? value[0] : 1
+        const y = typeof value[1] === "number" ? value[1] : 1
+        return new CS.UnityEngine.UIElements.StyleScale(
+            new CS.UnityEngine.UIElements.Scale(new CS.UnityEngine.Vector3(x, y, 1))
+        )
+    }
+    if (typeof value === "object" && value !== null) {
+        try { return new CS.UnityEngine.UIElements.StyleScale(value) } catch { return value }
+    }
+    return value
+}
+
+/**
+ * Parse transformOrigin style: [x, y] array or C# TransformOrigin pass-through
+ */
+function parseTransformOriginStyle(value: unknown): unknown {
+    if (Array.isArray(value)) {
+        const x = parseLengthForTransform(value[0])
+        const y = parseLengthForTransform(value[1])
+        if (x !== null && y !== null) {
+            return new CS.UnityEngine.UIElements.StyleTransformOrigin(
+                new CS.UnityEngine.UIElements.TransformOrigin(x, y)
+            )
+        }
+    }
+    if (typeof value === "object" && value !== null) {
+        try { return new CS.UnityEngine.UIElements.StyleTransformOrigin(value) } catch { return value }
+    }
+    return value
+}
+
 /**
  * Parse a style value based on the property name
  * @param key - Style property name (e.g., "width", "backgroundColor")
@@ -399,6 +533,12 @@ export function parseStyleValue(key: string, value: unknown): unknown {
         // Fall through if parsing failed
     }
 
+    // Transform properties
+    if (key === "translate") return parseTranslateStyle(value)
+    if (key === "rotate") return parseRotateStyle(value)
+    if (key === "scale") return parseScaleStyle(value)
+    if (key === "transformOrigin") return parseTransformOriginStyle(value)
+
     // Unknown property - pass through unchanged
     return value
 }

package/src/types.ts

@@ -167,13 +167,31 @@ export interface ViewStyle {
   unitySliceScale?: number;
 
   // Transform
-  /** Rotation transform. Pass a C# Rotate struct. */
+  /**
+   * Rotation transform.
+   * - number: degrees (e.g., 45)
+   * - string: with unit (e.g., "0.5turn", "1.57rad", "45deg", "50grad")
+   * - C# Rotate struct: pass-through (auto-wrapped in StyleRotate)
+   */
   rotate?: any;
-  /** Scale transform. Pass a C# Scale struct. */
+  /**
+   * Scale transform.
+   * - number: uniform scale (e.g., 1.5)
+   * - [x, y]: non-uniform scale (e.g., [1.5, 2])
+   * - C# Scale struct: pass-through (auto-wrapped in StyleScale)
+   */
   scale?: any;
-  /** Translation transform. Pass a C# Translate struct. */
+  /**
+   * Translation transform.
+   * - [x, y]: numbers are px, strings parsed (e.g., [10, 20] or ["50%", 10])
+   * - C# Translate struct: pass-through (auto-wrapped in StyleTranslate)
+   */
   translate?: any;
-  /** Transform origin point. Pass a C# TransformOrigin struct. */
+  /**
+   * Transform origin point.
+   * - [x, y]: numbers are px, strings parsed (e.g., ["50%", "50%"])
+   * - C# TransformOrigin struct: pass-through (auto-wrapped in StyleTransformOrigin)
+   */
   transformOrigin?: any;
 
   // Transition
@@ -510,7 +528,9 @@ export interface ScrollViewProps extends BaseProps {
 }
 
 export interface ImageProps extends BaseProps {
-  /** Image source - can be a Texture2D, Sprite, or path string */
+  /** Path to image asset relative to the assets/ folder (convenience prop) */
+  src?: string;
+  /** Pre-loaded Texture2D object (use when you loaded the texture yourself) */
   image?: object;
   /** Sprite to display (alternative to image) */
   sprite?: object;
@@ -636,7 +656,13 @@ export interface ScrollViewElement extends VisualElement {
 }
 
 export interface ImageElement extends VisualElement {
-  // Image-specific properties handled via style.backgroundImage
+  image: any;
+  sprite: any;
+  vectorImage: any;
+  scaleMode: number;
+  tintColor: any;
+  sourceRect: any;
+  uv: any;
 }
 
 // ListView uses Unity's virtualization callbacks directly