# OneJS Documentation

> Build cross-platform apps and games with React 19, powered by Unity's GPU-accelerated rendering.

Source: https://v3.onejs.com/docs

---

<!-- source: https://v3.onejs.com/docs/introduction -->
<!-- section: Getting Started -->

# Introduction

OneJS lets you build UIs with React and TypeScript that render through Unity's GPU-accelerated graphics pipeline. Write familiar web code, deploy everywhere Unity runs.

## Two Worlds, One Runtime

OneJS bridges **web development** and **game engines**:

- Use **React 19**, hooks, JSX, and the npm ecosystem
- Render through **Unity's UI Toolkit** - GPU-accelerated, not a webview
- Access **any C# API** directly from JavaScript
- Deploy to **desktop, mobile, web, consoles, and VR/AR** from one codebase

## For App Developers

If you're building cross-platform applications, your current options have painful tradeoffs:

| Solution | Problem |
|----------|---------|
| Electron | Ships Chromium (~150MB), high RAM usage, CPU-bound rendering |
| Tauri/WebView | Still browser rendering under the hood |
| Flutter | Different language (Dart), different ecosystem |
| React Native | Mobile-focused, limited desktop support |

**OneJS offers something different:**

- **True GPU rendering** - UI Toolkit renders on the GPU, not a browser engine
- **No webview overhead** - No DOM, no layout engine, no Chromium
- **React you already know** - Hooks, components, JSX, TypeScript
- **Unity's capabilities** - Mix 2D UI with 3D scenes, use shaders, physics, audio
- **Smaller builds** - No bundled browser engine

## For Game Developers

Game UI development has been stuck in the past - verbose C# code, slow iteration, limited modding support.

OneJS brings modern practices to game UI:

- **Declarative components** - Write UI as React components, not imperative C# code
- **Hot reload** - See changes instantly without recompiling
- **Separation of concerns** - UI logic in JavaScript, game logic in C#
- **First-class modding** - Players can modify UI without touching game code
- **Web dev accessibility** - Expand your team with JavaScript developers

## Platform Support

From a single React codebase:

| Platform | Notes |
|----------|-------|
| Windows, macOS, Linux | Desktop builds |
| iOS, Android | Mobile builds |
| WebGL | Browser builds (uses V8/SpiderMonkey with JIT) |
| PlayStation, Xbox, Switch | Console builds |
| VR/AR | XR device builds |

## How It Works

```
React Components → onejs-react Reconciler → UI Toolkit Elements → GPU Rendering
```

When you write:

```tsx
<Button text="Click me" onClick={() => console.log("clicked")} />
```

OneJS creates a real `UnityEngine.UIElements.Button` and wires up the event handler. React's diffing algorithm ensures only changed properties update.

## Developer Experience

- **TypeScript** - Full type definitions for Unity APIs
- **Hot Reload** - Changes appear instantly during development
- **CSS Modules** - Scoped styles with `.module.uss` files
- **Tailwind CSS** - Utility-first styling, automatically escaped for USS
- **npm Packages** - Use libraries from the JavaScript ecosystem
- **C# Interop** - Call any Unity API with `CS.UnityEngine.*`
- **AI-friendly** - Point Cursor/Claude/ChatGPT at [/llms-full.txt](/llms-full.txt) for full-docs context

## Requirements

- Unity 6.3 or later
- Node.js 18+ (for TypeScript compilation)

## Next Steps

- [Quick Start](/docs/quickstart) - Get OneJS running and build your first UI
- [Comparison](/docs/comparison) - Deep dive into the value proposition

---

<!-- source: https://v3.onejs.com/docs/quickstart -->
<!-- section: Getting Started -->

# Quick Start

Install OneJS and build a working UI component in your Unity project.

## Install

Open **Window > Package Manager**, click **+** > **Add package from git URL**, and enter:

```bash
https://github.com/Singtaa/OneJS.git#onejs-v3
```

Or clone directly into your Assets folder:

```bash
cd YourProject/Assets
git clone -b onejs-v3 https://github.com/Singtaa/OneJS.git
```

## Set Up a Project

1. Create a new GameObject and add the **JSRunner** component
2. Click **Initialize Project** in the inspector
3. Enter Play Mode

JSRunner handles everything: installs dependencies, builds the bundle, and starts a file watcher. The first run takes a moment while packages install; once it's done, the starter UI appears in the Game view.

Your project folder lives next to your scene, named after the GameObject:

```
Assets/Scenes/YourScene/
└── App/                      # Named after your GameObject
    ├── ~/                    # Working directory (~ = Unity ignores)
    │   ├── index.tsx         # Entry point
    │   ├── package.json
    │   ├── tsconfig.json
    │   └── esbuild.config.mjs
    ├── app.js.txt            # Built bundle
    └── PanelSettings.asset   # Project marker
```

## Write a Component

Open `~/index.tsx` and replace its contents:

```tsx
import { render, View, Label, Button } from "onejs-react"
import { useState } from "react"

function Counter() {
    const [count, setCount] = useState(0)

    return (
        <View style={{ padding: 20, alignItems: "flex-start" }}>
            <Label text={`Count: ${count}`} style={{ fontSize: 24, marginBottom: 10 }} />
            <Button text="Increment" onClick={() => setCount(c => c + 1)} />
        </View>
    )
}

render(<Counter />, __root)
```

Save the file. JSRunner automatically watches for changes, rebuilds, and hot-reloads. The UI updates in the Game view without leaving the editor. This is standard React: `useState`, JSX, component composition. The difference is that `<Button>` creates a real `UnityEngine.UIElements.Button` rendered on the GPU.

## Calling C#

Access any C# API through the `CS` global:

```tsx
function DebugButton() {
    const handleClick = () => {
        CS.UnityEngine.Debug.Log("Hello from JS!")
        console.log(`Time: ${CS.UnityEngine.Time.time}`)
    }

    return <Button text="Debug" onClick={handleClick} />
}
```

This works with all Unity APIs, your own game code, and third-party libraries.

## Quick Prototyping with JSPad

For quick experiments without file setup, use **JSPad** instead:

1. Add the **JSPad** component to a GameObject
2. Write TSX directly in the inspector
3. Click **Build**, then enter Play Mode

JSPad is self-contained. The bundle lives in the scene file. Great for learning and quick tests. Use JSRunner for real projects.

## Coming from V2?

| V2 | V3 |
|----|-----|
| ScriptEngine + Runner + Bundler | Single JSRunner component |
| Project-root `App/` folder | Scene Folder convention |
| Shared PanelSettings | Per-instance (auto-created) |
| `npm run setup` to initialize | "Initialize Project" button |
| Preact | React 19 |
| Separate Tailwind watcher | Built-in (`import "onejs:tailwind"`) |

## Next Steps

- [C# Interop](/docs/core-concepts/csharp-interop): calling C# from JavaScript
- [Styling](/docs/core-concepts/styling): USS, CSS Modules, and Tailwind
- [Components](/docs/components/view): all available UI components

---

<!-- source: https://v3.onejs.com/docs/comparison -->
<!-- section: Getting Started -->

# Comparison

OneJS uses Unity as a cross-platform runtime, giving you React development with GPU-accelerated rendering across desktop, mobile, web, consoles, and XR.

## Bundle Sizes

OneJS bundle size varies by platform since it includes the Unity runtime:

| Platform | OneJS | Notes |
|----------|-------|-------|
| WebGL | 3-5 MB | Browser handles JS execution |
| Android | ~35 MB | Includes IL2CPP runtime |
| iOS | ~40 MB | Similar to Android |
| Desktop | ~75 MB | Full standalone runtime |

These sizes depend on Unity version and included features. Stripping unused code reduces them further.

## Framework Comparison

| | Electron | Tauri | Flutter | React Native | OneJS |
|--|----------|-------|---------|--------------|-------|
| **Bundle size** | 100-150 MB | 3-10 MB | 5-40 MB | 4-25 MB | 3-75 MB* |
| **Rendering** | CPU (Chromium) | System webview | Skia (GPU) | Native views | GPU (UI Toolkit) |
| **Desktop** | ✓ | ✓ | ✓ | Limited | ✓ |
| **Mobile** | ✗ | Beta | ✓ | ✓ | ✓ |
| **Web** | ✗ | ✗ | ✓ | ✗ | ✓ |
| **Consoles** | ✗ | ✗ | ✗ | ✗ | ✓ |
| **VR/AR** | ✗ | ✗ | ✗ | ✗ | ✓ |
| **3D support** | WebGL only | WebGL only | Limited | Limited | Full engine |
| **Language** | JS/TS | JS/TS + Rust | Dart | JS/TS | JS/TS |
| **Consistency** | High | Varies | High | Varies | High |

*OneJS size is platform-dependent: WebGL ~5MB, mobile ~35MB, desktop ~75MB.

### When to Choose Each

**Electron** - Desktop-only apps where download size doesn't matter. Mature ecosystem.

**Tauri** - Smallest desktop bundles. Accept webview inconsistencies across platforms.

**Flutter** - Mobile-first apps. Willing to learn Dart.

**React Native** - Mobile apps with native UI components. Desktop is secondary.

**OneJS** - Cross-platform including consoles/XR. Need 3D capabilities. Want React with GPU rendering.

## For Game Developers

Traditional game UI (C#/C++) means slow iteration and verbose code. OneJS brings:

**Declarative components** instead of imperative code:

```tsx
// OneJS
function MainMenu() {
    return <Button text="Play" onClick={handlePlay} />
}
```

```csharp
// Traditional C#
var button = new Button();
button.text = "Play";
button.clicked += OnPlayClicked;
container.Add(button);
```

**Hot reload** - Change UI without recompiling or restarting play mode.

**Modding** - Players can modify JavaScript UI without touching compiled code.

**Web developer onboarding** - React developers contribute immediately.

## Technical Details

### JavaScript Engine

- **Native platforms**: QuickJS interpreter (works on iOS/consoles where JIT is prohibited)
- **WebGL**: Browser's V8/SpiderMonkey with full JIT optimization

### UI Toolkit

Unity's retained-mode UI system with flexbox layout, CSS-like styling, and GPU rendering. React's reconciler maps directly to UI Toolkit elements.

## Getting Started

- [Quick Start](/docs/quickstart) - Add OneJS to your project and build your first UI
- [Architecture](/docs/core-concepts/architecture) - Understand the internals

---

<!-- source: https://v3.onejs.com/docs/core-concepts/architecture -->
<!-- section: Core Concepts -->

# Architecture

OneJS connects JavaScript to Unity through several layers.

## Architecture Overview

```
┌─────────────────────────────────────────────────┐
│                  Your React Code                │
├─────────────────────────────────────────────────┤
│              onejs-react Reconciler             │
├─────────────────────────────────────────────────┤
│           QuickJS JavaScript Engine             │
├─────────────────────────────────────────────────┤
│     QuickJSUIBridge (Events, Scheduling)        │
├─────────────────────────────────────────────────┤
│              UI Toolkit Elements                │
└─────────────────────────────────────────────────┘
```

## The JavaScript Engine

OneJS uses **QuickJS**, a small embeddable JavaScript engine. It runs your code in an isolated context with:

- Full ES2020 support
- Async/await and Promises
- Modules (ESM)

QuickJS is interpreted, not JIT-compiled, so it works on iOS and other AOT/IL2CPP platforms where JIT is prohibited. For WebGL builds, OneJS uses the browser's native JavaScript engine instead.

## The React Reconciler

`onejs-react` is a custom React reconciler. When you write:

```tsx
<View style={{ padding: 20 }}>
    <Label text="Hello" />
</View>
```

The reconciler:
1. Creates a `VisualElement` for the View
2. Creates a `Label` element
3. Sets the style properties
4. Adds the Label as a child of the View

React's diffing algorithm handles updates efficiently. Only changed properties are updated.

## Component Mapping

| React Component | UI Toolkit Element |
|-----------------|-------------------|
| `<View>` | `VisualElement` |
| `<Text>` | `TextElement` |
| `<Label>` | `Label` |
| `<Button>` | `Button` |
| `<TextField>` | `TextField` |
| `<Toggle>` | `Toggle` |
| `<Slider>` | `Slider` |
| `<ScrollView>` | `ScrollView` |
| `<Image>` | `Image` |
| `<ListView>` | `ListView` |
| `<FrostedGlass>` | `FrostedGlassElement` |
| Raw text | `TextElement` |

**Text handling:** Raw text children (e.g., `<View>Hello</View>`) automatically create `TextElement` instances. Use `<Text>` for primary text display and `<Label>` for form labels.

## C# Interop

The `CS` global proxy uses reflection to access C# types:

```javascript
CS.UnityEngine.Debug.Log("Hello")
```

This resolves to:
1. Look up the `UnityEngine.Debug` type
2. Find the `Log` method
3. Convert arguments to C# types
4. Invoke the method
5. Convert the return value back to JavaScript

Objects returned from C# are wrapped in proxies with integer handles. Property access and method calls go through the interop layer.

## Event System

UI Toolkit events are captured and routed to JavaScript:

1. C# registers a TrickleDown callback on the root element
2. When an event fires, it's serialized to JSON
3. `__dispatchEvent(handle, eventType, data)` is called
4. JavaScript looks up handlers and invokes them

```
UI Event → C# Capture → JSON Serialize → JS Dispatch → Your Handler
```

## Scheduling

OneJS provides familiar timing APIs:

- `requestAnimationFrame()`: Called every Unity Update
- `setTimeout()` / `setInterval()`: Timer queue processed each frame
- `queueMicrotask()`: For Promise resolution

The bridge's `Tick()` method drives all scheduling from Unity's Update loop.

## Memory Management

C# objects referenced from JavaScript are tracked with integer handles:

1. C# object → Handle registered in table
2. JavaScript proxy wraps the handle
3. When JS object is garbage collected → FinalizationRegistry releases handle
4. C# object becomes eligible for GC

Manual cleanup is available via `releaseObject()` but rarely needed.

## Application Lifecycle

OneJS runs your code in two contexts: **edit-mode preview** (renders UI without Play mode) and **play mode**. Export lifecycle hooks to control when game logic runs:

```
Edit-mode preview:
  InitializeBridge → RunScript (module-level code runs) → EditModeTick at 30Hz

Play mode:
  InitializeBridge → RunScript → onPlay()
  → Update every frame
  → File change → onStop() → teardown → rebuild → onPlay()
  → Exit Play mode → onStop()
```

- **Module-level code** (including `render()`) runs in both modes, safe for UI
- **`onPlay()`** fires only in play mode, after the bundle loads
- **`onStop()`** fires before teardown (play mode exit or live reload)
- **`__isPlaying`** global: `true` in play mode, `false` in edit-mode preview

## WebGL Differences

On WebGL, JavaScript runs in the browser's V8/SpiderMonkey engine:

- JIT compilation (faster execution)
- Browser's native RAF loop
- No QuickJS overhead

The same code runs on both platforms. Only the underlying engine changes.

---

<!-- source: https://v3.onejs.com/docs/core-concepts/csharp-interop -->
<!-- section: Core Concepts -->

# C# Interop

The `CS` global gives you access to any C# type.

## Accessing Types

Access C# types through their full namespace:

```javascript
// Static methods and properties
CS.UnityEngine.Debug.Log("Hello from JS!")
const dt = CS.UnityEngine.Time.deltaTime

// Create instances
const vec = new CS.UnityEngine.Vector3(1, 2, 3)
console.log(vec.x, vec.y, vec.z)
```

Your own code works the same way:

```csharp
// C#
namespace MyGame {
    public class GameManager {
        public static int Score { get; set; }
        public static void AddScore(int points) { Score += points; }
    }
}
```

```javascript
CS.MyGame.GameManager.AddScore(100)
const score = CS.MyGame.GameManager.Score
```

### ES6 Imports

With esbuild's import transform plugin, you can use ES6 import syntax instead of `CS.*`:

```tsx
import { GameObject, Rigidbody } from "UnityEngine"
import { GameManager } from "MyGame"

const go = new GameObject("Player")
go.AddComponent(Rigidbody)
GameManager.AddScore(100)
```

This is the preferred style for app code. The examples below use it where applicable.

## Working with Objects

Use `new` to create C# objects. Properties and fields are accessed with dot notation:

```tsx
import { GameObject, Rigidbody, MeshRenderer } from "UnityEngine"

const go = new GameObject("MyObject")

const rb = go.AddComponent(Rigidbody)
rb.mass = 2.0
rb.useGravity = true

const pos = go.transform.position
console.log(pos.x, pos.y, pos.z)
```

This works for any C# type: structs, classes, and your own types all use dot notation.

> **Note:** `console.log(obj)` on a C# object shows its proxy handle (e.g. `[CSObject ?#27]`), not the field values. To see actual data, log the fields directly: `console.log(obj.x, obj.y)`.

## Enums

Access enum values directly:

```tsx
import { Space, Vector3, KeyCode } from "UnityEngine"

transform.Translate(new Vector3(1, 0, 0), Space.World)

if (keyCode === KeyCode.Space) {
    console.log("Space pressed!")
}
```

## Generic Types

Create bound generic types with function-call syntax:

```tsx
import { List, Dictionary } from "System.Collections.Generic"
import { Int32, String } from "System"

const numbers = new (List(Int32))()
numbers.Add(1)
numbers.Add(2)

const scores = new (Dictionary(String, Int32))()
scores.set_Item("player1", 100)
```

### Generic Methods

Generic *methods* (e.g., `Create<T>()`, `GetValue<T>()`) are not supported by the interop layer. Only generic *types* like `List<T>` and `Dictionary<TKey, TValue>` work, using the function-call syntax shown above.

The workaround is to add a non-generic wrapper method in C#:

```csharp
// Instead of calling Create<MyThing>() from JS,
// add a non-generic overload in C#:
public Task<MyThing> CreateMyThing(CancellationToken ct) => Create<MyThing>(ct);
```

```tsx
// Then call the non-generic version from JS
const result = await factory.CreateMyThing(cancellationToken)
```

## Arrays and Collections

C# collections use `.Length`/`.Count` and indexers:

```tsx
import { Renderer } from "UnityEngine"

const renderers = go.GetComponentsInChildren(Renderer)
for (let i = 0; i < renderers.Length; i++) {
    renderers[i].enabled = false
}
```

Use `toArray` from `onejs-react` to convert to JS arrays for `.map()`, `.filter()`, etc.:

```tsx
import { toArray } from "onejs-react"

const items = toArray(inventory.Items)
items.map(item => console.log(item.Name))

// Safe with null, returns []
const npcs = toArray(currentPlace?.NPCs)
```

Both `List<T>` and `T[]` work with `toArray`.

## Async Methods

C# `async Task` methods return Promises:

```csharp
// C#
public class DataLoader {
    public static async Task<string> LoadDataAsync(string url) { ... }
}
```

```tsx
import { DataLoader } from "MyGame"

const data = await DataLoader.LoadDataAsync("/api/data")
```

See [Async C# Methods](/docs/guides/async-csharp) for error handling and React patterns.

## Events and Delegates

### Delegate Fields

For C# **delegate fields** (`Action`, `Action<T>`, etc.), assign a JS function directly. This replaces any existing handler:

```csharp
// C#
public struct PlayerData {
    public string name;
    public int score;
}

public class NetworkManager {
    public static Action OnConnected;
    public static Action<PlayerData> OnPlayerJoined;
}
```

```tsx
import { NetworkManager } from "MyGame"

// No parameters
NetworkManager.OnConnected = () => console.log("Connected!")

// Typed parameter, access fields directly
NetworkManager.OnPlayerJoined = (player) => {
    console.log(player.name, player.score)
}

// Clear with null
NetworkManager.OnConnected = null
```

### C# Events

For C# **events**, use `add_`/`remove_` (equivalent to `+=`/`-=`). Events support multiple subscribers:

```tsx
const handler = () => console.log("Players changed!")
GameManager.add_OnPlayersChanged(handler)
GameManager.remove_OnPlayersChanged(handler)  // must pass the same reference
```

### React Cleanup

Clean up subscriptions in `useEffect` to avoid leaks during hot reload:

```tsx
// Delegate field: assign and clear
useEffect(() => {
    NetworkManager.OnPlayerJoined = (player) => {
        setPlayers(prev => [...prev, { name: player.name, score: player.score }])
    }
    return () => { NetworkManager.OnPlayerJoined = null }
}, [])

// C# event: add and remove
useEffect(() => {
    const handler = () => setCount(GameManager.PlayerCount)
    GameManager.add_OnPlayersChanged(handler)
    return () => GameManager.remove_OnPlayersChanged(handler)
}, [])
```

<Callout>
`useEffect` cleanup works for hot reload, but **won't run during scene transitions** because Unity destroys the JSRunner before React can run cleanup functions. If your app uses multiple scenes, null out static delegates in `onStop` instead:

```tsx
export function onStop() {
    NetworkManager.OnPlayerJoined = null
}
```

See [Lifecycle Hooks](/docs/guides/project-setup#lifecycle-hooks) for details on `onStop`.
</Callout>

## Extension Methods

C# extension methods aren't discoverable via reflection on the target type. Use `useExtensions` to register them (like a C# `using` statement):

```tsx
useExtensions(CS.UnityEngine.UIElements.PointerCaptureHelper)

const el = ref.current
el.CapturePointer(0)       // PointerCaptureHelper.CapturePointer(el, 0)
el.ReleasePointer(0)       // PointerCaptureHelper.ReleasePointer(el, 0)
```

```tsx
useExtensions(CS.UnityEngine.ImageConversion)

const tex = new CS.UnityEngine.Texture2D(2, 2)
tex.LoadImage(bytes)  // ImageConversion.LoadImage(tex, bytes)
```

Call `useExtensions` once per static class at module level.

## Common Patterns

### Async Alternatives to Coroutines

JS has `async`/`await` and `requestAnimationFrame`, so you often don't need C# coroutines:

```tsx
import { Time, Color } from "UnityEngine"

async function fadeOut(renderer, duration) {
    const start = Time.time
    while (true) {
        await new Promise(r => requestAnimationFrame(r))
        const t = Math.min((Time.time - start) / duration, 1)
        renderer.material.color = new Color(1, 1, 1, 1 - t)
        if (t >= 1) break
    }
}
```

### Per-Frame Logic

```tsx
import { Input, KeyCode } from "UnityEngine"

function update() {
    if (Input.GetKeyDown(KeyCode.Space)) {
        console.log("Jump!")
    }
    requestAnimationFrame(update)
}
requestAnimationFrame(update)
```

## Performance Tips

1. **Cache type references**: avoid repeated lookups in hot loops
2. **Batch property access**: read multiple values at once when possible
3. **Use fast paths**: common operations like `Time.deltaTime` are optimized

For performance-critical code running every frame, see the [Zero-Allocation Interop](/docs/guides/zero-alloc) guide.

---

<!-- source: https://v3.onejs.com/docs/core-concepts/styling -->
<!-- section: Core Concepts -->

# Styling

OneJS supports inline styles, USS (Unity Style Sheets), [CSS Modules](/docs/guides/css-modules), and [Tailwind](/docs/guides/tailwind) (built-in, no external dependencies).

## Inline Styles

Apply styles directly to elements:

```tsx
<View
    style={{
        width: 200,
        height: 100,
        backgroundColor: "#1a1a1a",
        padding: 20,
        borderRadius: 8,
    }}
>
    <Label text="Styled content" style={{ color: "#ffffff" }} />
</View>
```

## Value Types

**Numbers**: Interpreted as pixels:

```tsx
style={{ width: 100, padding: 20 }}
```

**Strings**: For percentages, keywords, or complex values:

```tsx
style={{ width: "50%", height: "auto" }}
```

**Colors**: Hex, rgb, rgba, or named colors:

```tsx
style={{
    backgroundColor: "#ff0000",
    color: "rgb(255, 255, 255)",
    borderColor: "rgba(0, 0, 0, 0.5)",
}}
```

## Layout Properties

### Dimensions

```tsx
style={{
    width: 200,
    height: 100,
    minWidth: 50,
    maxWidth: 400,
    minHeight: 50,
    maxHeight: 300,
}}
```

### Flexbox

```tsx
style={{
    flexDirection: "row",      // "row" | "column" | "row-reverse" | "column-reverse"
    flexWrap: "wrap",          // "nowrap" | "wrap" | "wrap-reverse"
    justifyContent: "center",  // "flex-start" | "center" | "flex-end" | "space-between" | "space-around"
    alignItems: "center",      // "flex-start" | "center" | "flex-end" | "stretch"
    alignContent: "center",
    flexGrow: 1,
    flexShrink: 0,
    flexBasis: "auto",
}}
```

### Spacing

```tsx
style={{
    // Shorthand (applies to all sides)
    margin: 10,
    padding: 20,

    // Or individual sides
    marginTop: 10,
    marginRight: 10,
    marginBottom: 10,
    marginLeft: 10,
    paddingTop: 20,
    paddingRight: 20,
    paddingBottom: 20,
    paddingLeft: 20,
}}
```

Shorthands like `margin`, `padding`, `borderWidth`, `borderColor`, and `borderRadius` are automatically expanded to individual properties.

### Positioning

```tsx
style={{
    position: "absolute",  // "relative" | "absolute"
    top: 10,
    right: 10,
    bottom: 10,
    left: 10,
}}
```

## Visual Properties

### Backgrounds

```tsx
style={{
    backgroundColor: "#2a2a2a",
    backgroundImage: texture,  // Texture2D or RenderTexture
}}
```

Background images accept Unity `Texture2D`, `RenderTexture`, or GPU compute RenderTextures:

```tsx
import { loadImage } from "onejs-unity/assets"

function Card() {
    const [texture, setTexture] = useState(null)

    useEffect(() => {
        const tex = loadImage("images/card-bg.png")
        setTexture(tex)
    }, [])

    return (
        <View style={{ backgroundImage: texture, width: 200, height: 150 }}>
            <Label text="Card Content" />
        </View>
    )
}
```

### Borders

```tsx
style={{
    borderWidth: 1,
    borderColor: "#333333",
    borderRadius: 8,
    // Or individual sides
    borderTopWidth: 2,
    borderLeftColor: "#ff0000",
    borderTopLeftRadius: 4,
}}
```

### Display

```tsx
style={{
    display: "flex",     // "flex" | "none"
    visibility: "visible", // "visible" | "hidden"
    overflow: "hidden",  // "visible" | "hidden"
    opacity: 0.8,
}}
```

## Typography

```tsx
<Label
    text="Styled text"
    style={{
        fontSize: 16,
        color: "#ffffff",
        unityFontStyleAndWeight: "bold", // "normal" | "bold" | "italic" | "bold-and-italic"
        unityTextAlign: "middle-center", // Text alignment
        whiteSpace: "normal",            // "normal" | "nowrap"
        letterSpacing: 2,
        wordSpacing: 4,
    }}
/>
```

### Custom Fonts

Use `loadFontDefinition` from `onejs-unity/assets` to load a font and apply it via `unityFontDefinition`:

```tsx
import { loadFontDefinition } from "onejs-unity/assets"

function StyledText() {
    const [fontDef, setFontDef] = useState(null)

    useEffect(() => {
        const def = loadFontDefinition("fonts/Consolas-Regular.ttf")
        setFontDef(def)
    }, [])

    return (
        <Label style={{ unityFontDefinition: fontDef, fontSize: 18 }}>
            Custom font text
        </Label>
    )
}
```

### Text Overflow

```tsx
style={{
    textOverflow: "ellipsis",                // "clip" | "ellipsis"
    unityTextOverflowPosition: "end",        // "end" | "start" | "middle"
    whiteSpace: "nowrap",                    // Required for ellipsis to work
}}
```

### Text Outline

```tsx
style={{
    unityTextOutlineColor: "#000000",
    unityTextOutlineWidth: 1,
}}
```

### All Typography Properties

| Property | Type | Values |
|----------|------|--------|
| `fontSize` | Length | `16`, `"16px"` |
| `color` | Color | `"#fff"`, `"rgb(255,0,0)"` |
| `unityFont` | object | C# `Font` object |
| `unityFontDefinition` | object | C# `FontDefinition` from `loadFontDefinition()` |
| `unityFontStyleAndWeight` | enum | `"normal"`, `"bold"`, `"italic"`, `"bold-and-italic"` |
| `unityTextAlign` | enum | `"upper-left"`, `"middle-center"`, etc. |
| `whiteSpace` | enum | `"normal"`, `"nowrap"` |
| `letterSpacing` | Length | `2`, `"2px"` |
| `wordSpacing` | Length | `4`, `"4px"` |
| `unityParagraphSpacing` | Length | `10`, `"10px"` |
| `unityTextOutlineColor` | Color | `"#000"` |
| `unityTextOutlineWidth` | Length | `1`, `"1px"` |
| `textOverflow` | enum | `"clip"`, `"ellipsis"` |
| `unityTextOverflowPosition` | enum | `"end"`, `"start"`, `"middle"` |

## Background Image Tint

Tint the background image with a color:

```tsx
style={{
    backgroundImage: texture,
    unityBackgroundImageTintColor: "rgba(255, 0, 0, 0.5)",
}}
```

## 9-Slice

Control how background images are sliced for scalable UI:

```tsx
style={{
    backgroundImage: texture,
    unitySliceTop: 12,
    unitySliceRight: 12,
    unitySliceBottom: 12,
    unitySliceLeft: 12,
    unitySliceScale: 1,
}}
```

## Transform

Apply rotation, scale, and translation transforms using friendly shorthand values:

```tsx
style={{
    translate: [30, 0],
    rotate: 45,
    scale: 1.5,
    transformOrigin: ["50%", "50%"],
}}
```

### translate

Accepts `[x, y]` where values are numbers (px) or strings (`"50%"`, `"10px"`):

```tsx
style={{ translate: [30, 0] }}       // 30px right
style={{ translate: [0, 20] }}       // 20px down
style={{ translate: ["50%", 0] }}    // 50% of own width
style={{ translate: ["50%", "50%"] }}
```

### rotate

Accepts a number (degrees) or string with unit:

```tsx
style={{ rotate: 45 }}           // 45 degrees
style={{ rotate: "0.5turn" }}    // half turn (180deg)
style={{ rotate: "45deg" }}
style={{ rotate: "1.57rad" }}
```

### scale

Accepts a number (uniform) or `[x, y]`:

```tsx
style={{ scale: 1.5 }}           // 150% on both axes
style={{ scale: 0.5 }}           // 50% on both axes
style={{ scale: [2, 0.5] }}      // stretch horizontal, squash vertical
```

### transformOrigin

Accepts `[x, y]` (same value types as translate):

```tsx
style={{ transformOrigin: ["0%", "0%"], rotate: 30 }}     // top-left pivot
style={{ transformOrigin: ["50%", "50%"], rotate: 30 }}    // center pivot
style={{ transformOrigin: ["100%", "100%"], rotate: 30 }}  // bottom-right pivot
```

### C# Struct Pass-through

You can also pass C# structs directly. They are auto-wrapped in `Style*` types:

```tsx
const UIE = CS.UnityEngine.UIElements

style={{
    translate: new UIE.Translate(
        new UIE.Length(30, UIE.LengthUnit.Pixel),
        new UIE.Length(0, UIE.LengthUnit.Pixel)
    ),
    rotate: new UIE.Rotate(UIE.Angle.Degrees(45)),
}}
```

## Transitions

Animate style changes with transitions. These accept C# `StyleList` values:

```tsx
style={{
    transitionProperty: /* StyleList of property names */,
    transitionDuration: /* StyleList of TimeValue */,
    transitionDelay: /* StyleList of TimeValue */,
    transitionTimingFunction: /* StyleList of EasingFunction */,
}}
```

For most use cases, transitions are easier to define in USS:

```css
.animated {
    transition-property: background-color, opacity;
    transition-duration: 0.3s;
    transition-timing-function: ease-in-out;
}
```

## Other Properties

| Property | Type | Values |
|----------|------|--------|
| `unityOverflowClipBox` | enum | `"padding-box"`, `"content-box"` |
| `cursor` | object | C# `Cursor` struct |

## USS Stylesheets

For reusable styles, use USS files:

```css
/* styles/main.uss */
.card {
    background-color: #2a2a2a;
    padding: 20px;
    border-radius: 8px;
    margin-bottom: 10px;
}

.card-title {
    font-size: 18px;
    color: #ffffff;
    margin-bottom: 10px;
}

.button-primary {
    background-color: #0066cc;
    color: #ffffff;
    padding: 10px 20px;
    border-radius: 4px;
}

.button-primary:hover {
    background-color: #0077ee;
}
```

Load and apply the stylesheet:

```tsx
// Load at startup
loadStyleSheet("styles/main.uss")

// Use classes
<View className="card">
    <Label text="Card Title" className="card-title" />
    <Button text="Action" className="button-primary" />
</View>
```

**Note:** [CSS Modules](/docs/guides/css-modules) and [Tailwind](/docs/guides/tailwind) embed styles directly in the JS bundle, so they work in builds automatically. USS files loaded via `loadStyleSheet()` are loaded from the filesystem and need to be placed in your `assets/` folder to be included in builds.

## StyleSheet API

OneJS provides functions for loading and managing stylesheets at runtime.

### loadStyleSheet

Load a USS file from the working directory:

```tsx
loadStyleSheet("styles/main.uss")  // Returns true if successful
```

### compileStyleSheet

Compile a USS string and apply it to the root element. If a stylesheet with the same name already exists, it will be replaced automatically (deduplication):

```tsx
const uss = `
.my-class {
    background-color: #333;
    padding: 10px;
}
`
compileStyleSheet(uss, "my-styles")  // Name used for deduplication
```

This is how [CSS Modules](/docs/guides/css-modules) and [Tailwind](/docs/guides/tailwind) work internally - they embed USS in the JavaScript bundle and call `compileStyleSheet()` at runtime.

### removeStyleSheet

Remove a specific stylesheet by name:

```tsx
removeStyleSheet("my-styles")  // Returns true if found and removed
```

### clearStyleSheets

Remove all JS-loaded stylesheets. Does not affect Unity asset-based stylesheets:

```tsx
const count = clearStyleSheets()  // Returns number of stylesheets removed
console.log(`Removed ${count} stylesheets`)
```

### Hot Reload Behavior

Stylesheets are automatically deduplicated by name. When you hot reload your app, re-importing CSS Modules or Tailwind won't accumulate duplicate styles - the existing stylesheet is replaced.

## USS Variables

Define reusable values with custom properties:

```css
:root {
    --accent: #FF6600;
    --spacing: 20px;
    --bg-dark: #333333;
}

.card {
    background-color: var(--bg-dark);
    padding: var(--spacing);
}

.card-title {
    color: var(--accent);
}
```

Use `var()` with a fallback value for when the variable is undefined:

```css
.text {
    color: var(--undefined-var, #00CCFF);
}
```

Variables work in all styling methods: plain USS files, [CSS Modules](/docs/guides/css-modules), and inline `compileStyleSheet()` calls.

**Limitations:** USS variables are simpler than CSS variables. `var()` cannot be nested inside other functions like `rgb()`, and mathematical operations are not supported.

## Pseudo-classes

USS supports pseudo-classes for interactive states:

```css
.button:hover {
    background-color: #333333;
}

.button:active {
    background-color: #444444;
}

.button:focus {
    border-color: #0066cc;
}

.input:focus {
    border-color: #0066cc;
    border-width: 2px;
}
```

## Combining Styles

Use both className and inline styles:

```tsx
<View
    className="card"
    style={{ width: 300 }}  // Inline overrides USS
>
    <Label text="Content" />
</View>
```

Inline styles take precedence over USS classes.

## Dynamic Styles

Compute styles based on state:

```tsx
function Button({ active, children }) {
    return (
        <View
            style={{
                backgroundColor: active ? "#0066cc" : "#333333",
                padding: 10,
                borderRadius: 4,
            }}
        >
            {children}
        </View>
    )
}
```

## Style Objects

Extract and reuse style objects:

```tsx
const styles = {
    container: {
        padding: 20,
        backgroundColor: "#1a1a1a",
    },
    title: {
        fontSize: 24,
        color: "#ffffff",
        marginBottom: 20,
    },
    button: {
        padding: 10,
        backgroundColor: "#0066cc",
        borderRadius: 4,
    },
}

function Screen() {
    return (
        <View style={styles.container}>
            <Label text="Title" style={styles.title} />
            <Button text="Click" style={styles.button} />
        </View>
    )
}
```

## Common Patterns

### Centering

```tsx
// Center children
<View style={{
    justifyContent: "center",
    alignItems: "center",
    height: "100%",
}}>
    <Label text="Centered" />
</View>
```

### Full Screen

```tsx
<View style={{
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
}}>
    {/* Content fills screen */}
</View>
```

### Responsive Width

```tsx
<View style={{
    width: "100%",
    maxWidth: 800,
    marginLeft: "auto",
    marginRight: "auto",
}}>
    {/* Centered, max 800px */}
</View>
```

## Debugging Styles

When USS selectors aren't applying as expected, use the built-in debugging utilities to inspect the visual tree.

### Dump Visual Tree

Use `__dumpUI()` to output the element hierarchy with USS classes:

```tsx
// Dump entire UI from root
console.log(__dumpUI())

// Dump specific element with depth limit
console.log(__dumpUI(myElement, 5))

// Include computed styles
console.log(__dumpUI(myElement, 5, true))
```

Output shows element types, names, and USS classes:

```
<VisualElement name="root" class="unity-ui-document">
  <VisualElement class="container">
    <Button class="unity-button btn-primary">
    </Button>
  </VisualElement>
</VisualElement>
```

### Find Elements by Class

Use `__findByClass()` to locate elements with a specific USS class:

```tsx
// Find all elements with class "btn-primary"
console.log(__findByClass("btn-primary"))
```

Returns element info including pseudo-states and computed styles:

```
Found 2 elements with class 'btn-primary':
  Type: Button
  Name: submit-btn
  Classes: [unity-button, btn-primary]
  Pseudo States: [:hover]
  Styles:
    backgroundColor: rgba(0.24, 0.47, 0.99, 1.00)
```

### Find Elements by Type

Use `__findByType()` to find all elements of a specific type:

```tsx
// Find all TextField elements
console.log(__findByType("TextField"))

// Find all Buttons
console.log(__findByType("Button"))
```

### Common Debugging Scenarios

**Selector not matching**: Dump the element to see its actual USS classes and verify your selector matches.

**Style not applying**: Check if a higher-specificity rule is overriding yours. Inline styles always win.

**Pseudo-class issues**: Use `__findByClass()` to see which pseudo-states (`:hover`, `:focus`, etc.) are active.

**Inherited styles**: Remember that UI Toolkit uses visual tree inheritance, not DOM inheritance. Dump the parent chain to trace style sources.

---

<!-- source: https://v3.onejs.com/docs/core-concepts/events -->
<!-- section: Core Concepts -->

# Events

Handle user interactions with React-style event props.

## Click Events

```tsx
<Button
    text="Click me"
    onClick={(e) => {
        console.log("Clicked at", e.x, e.y)
    }}
/>
```

## Pointer Events

Track pointer (mouse/touch) interactions:

```tsx
<View
    style={{ width: 200, height: 200, backgroundColor: "#333" }}
    onPointerDown={(e) => console.log("Down", e.x, e.y)}
    onPointerUp={(e) => console.log("Up")}
    onPointerMove={(e) => console.log("Move", e.x, e.y)}
    onPointerEnter={(e) => console.log("Enter")}
    onPointerLeave={(e) => console.log("Leave")}
>
    <Label text="Hover and click me" />
</View>
```

## Focus Events

```tsx
<TextField
    placeholder="Type here..."
    onFocus={(e) => console.log("Focused")}
    onBlur={(e) => console.log("Lost focus")}
/>
```

## Change Events

```tsx
<TextField value={text} onChange={(e) => setText(e.value)} />
<Toggle value={on} onChange={(e) => setOn(e.value)} label="Enable" />
<Slider value={vol} lowValue={0} highValue={100} onChange={(e) => setVol(e.value)} />
```

## Keyboard Events

```tsx
<TextField
    onKeyDown={(e) => {
        if (e.keyCode === CS.UnityEngine.KeyCode.Return) {
            console.log("Enter pressed!")
        }
    }}
/>
```

## Event Propagation

Events bubble up through the component tree. Use `stopPropagation()` to prevent this:

```tsx
<View onClick={() => console.log("Parent")}>
    <Button
        text="Click"
        onClick={(e) => {
            e.stopPropagation()
            console.log("Only this handler runs")
        }}
    />
</View>
```

## Pointer Capture

Lock pointer events to a specific element. Essential for reliable dragging. Without capture, fast pointer movement can leave the element's bounds and drop events.

```tsx
useExtensions(CS.UnityEngine.UIElements.PointerCaptureHelper)

function Draggable({ children }) {
    const ref = useRef(null)
    const [pos, setPos] = useState({ x: 0, y: 0 })
    const startPos = useRef({ x: 0, y: 0 })

    return (
        <View
            ref={ref}
            style={{ position: "absolute", left: pos.x, top: pos.y }}
            onPointerDown={(e) => {
                ref.current.CapturePointer(e.pointerId)
                startPos.current = { x: e.x - pos.x, y: e.y - pos.y }
            }}
            onPointerMove={(e) => {
                if (ref.current.HasPointerCapture(e.pointerId)) {
                    setPos({
                        x: e.x - startPos.current.x,
                        y: e.y - startPos.current.y,
                    })
                }
            }}
            onPointerUp={(e) => ref.current.ReleasePointer(e.pointerId)}
        >
            {children}
        </View>
    )
}
```

`useExtensions` registers C# extension methods so they can be called on elements. See [C# Interop: Extension Methods](/docs/core-concepts/csharp-interop#extension-methods) for details.

## Other Events

```tsx
// Geometry: detect size/position changes
<View onGeometryChanged={(e) => console.log(e.newRect)} />

// Transitions: monitor USS animations
<View
    onTransitionEnd={(e) => console.log("Done:", e.styleProperty)}
/>

// Navigation: gamepad/keyboard UI navigation
<View
    onNavigationMove={(e) => console.log("Direction:", e.direction)}
    onNavigationSubmit={(e) => console.log("Submit")}
/>

// Mouse-specific (prefer pointer events for cross-device support)
<View
    onMouseDown={(e) => console.log("Mouse", e.button)}
    onWheel={(e) => console.log("Scroll", e.delta.y)}
/>
```

## Event Object Properties

### Pointer / Mouse Event

| Property | Type | Description |
|----------|------|-------------|
| `type` | `string` | Event type name |
| `x` | `number` | X position |
| `y` | `number` | Y position |
| `button` | `number` | Mouse button (0=left, 1=middle, 2=right) |
| `pointerId` | `number` | Unique pointer identifier |

### Change Event

| Property | Type | Description |
|----------|------|-------------|
| `type` | `string` | Event type name |
| `value` | `T` | New value (type depends on control) |

## Event Mapping Reference

### Click & Pointer

| React Prop | UI Toolkit Event |
|------------|-----------------|
| `onClick` | `ClickEvent` |
| `onPointerDown` | `PointerDownEvent` |
| `onPointerUp` | `PointerUpEvent` |
| `onPointerMove` | `PointerMoveEvent` |
| `onPointerEnter` | `PointerEnterEvent` |
| `onPointerLeave` | `PointerLeaveEvent` |
| `onPointerCancel` | `PointerCancelEvent` |
| `onPointerCapture` | `PointerCaptureEvent` |
| `onPointerCaptureOut` | `PointerCaptureOutEvent` |
| `onPointerStationary` | `PointerStationaryEvent` |

### Mouse

| React Prop | UI Toolkit Event |
|------------|-----------------|
| `onMouseDown` | `MouseDownEvent` |
| `onMouseUp` | `MouseUpEvent` |
| `onMouseMove` | `MouseMoveEvent` |
| `onMouseEnter` | `MouseEnterEvent` |
| `onMouseLeave` | `MouseLeaveEvent` |
| `onMouseOver` | `MouseOverEvent` |
| `onMouseOut` | `MouseOutEvent` |
| `onWheel` | `WheelEvent` |
| `onContextClick` | `ContextClickEvent` |

### Focus & Input

| React Prop | UI Toolkit Event |
|------------|-----------------|
| `onFocus` | `FocusEvent` |
| `onBlur` | `BlurEvent` |
| `onFocusIn` | `FocusInEvent` |
| `onFocusOut` | `FocusOutEvent` |
| `onChange` | `ChangeEvent<T>` |
| `onInput` | `InputEvent` |
| `onKeyDown` | `KeyDownEvent` |
| `onKeyUp` | `KeyUpEvent` |

### Drag & Drop

| React Prop | UI Toolkit Event |
|------------|-----------------|
| `onDragEnter` | `DragEnterEvent` |
| `onDragLeave` | `DragLeaveEvent` |
| `onDragUpdated` | `DragUpdatedEvent` |
| `onDragPerform` | `DragPerformEvent` |
| `onDragExited` | `DragExitedEvent` |

### Layout & Transitions

| React Prop | UI Toolkit Event |
|------------|-----------------|
| `onGeometryChanged` | `GeometryChangedEvent` |
| `onTransitionRun` | `TransitionRunEvent` |
| `onTransitionStart` | `TransitionStartEvent` |
| `onTransitionEnd` | `TransitionEndEvent` |
| `onTransitionCancel` | `TransitionCancelEvent` |

### Navigation

| React Prop | UI Toolkit Event |
|------------|-----------------|
| `onNavigationMove` | `NavigationMoveEvent` |
| `onNavigationSubmit` | `NavigationSubmitEvent` |
| `onNavigationCancel` | `NavigationCancelEvent` |
| `onTooltip` | `TooltipEvent` |

## Custom Rendering

For custom drawing with `onGenerateVisualContent`, see the [Vector Drawing](/docs/guides/vector-drawing) guide.

---

<!-- source: https://v3.onejs.com/docs/core-concepts/refs -->
<!-- section: Core Concepts -->

# Refs & Direct Access

Use React refs to access the underlying UI Toolkit `VisualElement` directly. This is useful for imperative operations, measurements, or accessing features not exposed through props.

## Basic Usage

```tsx
import { useRef, useEffect } from "react"
import { View, Label } from "onejs-react"

function FocusableInput() {
    const inputRef = useRef(null)

    useEffect(() => {
        // Focus the element on mount
        inputRef.current?.Focus()
    }, [])

    return <TextField ref={inputRef} placeholder="Auto-focused" />
}
```

## VisualElement API

When you access `ref.current`, you get a proxy to the C# `VisualElement`. Available properties and methods:

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `__csHandle` | `number` | Internal C# object handle |
| `__csType` | `string` | C# type name |
| `name` | `string` | Element name |
| `visible` | `boolean` | Visibility state |
| `enabledSelf` | `boolean` | Whether element is enabled |
| `enabledInHierarchy` | `boolean` | Enabled state including parents |
| `focusable` | `boolean` | Whether element can receive focus |
| `style` | `object` | Inline style access |
| `childCount` | `number` | Number of children |
| `parent` | `VisualElement` | Parent element |

### Focus Methods

```tsx
const ref = useRef(null)

// Focus the element
ref.current?.Focus()

// Remove focus
ref.current?.Blur()
```

### Class List Methods

```tsx
const ref = useRef(null)

// Add USS class
ref.current?.AddToClassList("highlighted")

// Remove USS class
ref.current?.RemoveFromClassList("highlighted")

// Check if class exists
const hasClass = ref.current?.ClassListContains("highlighted")

// Clear all classes
ref.current?.ClearClassList()
```

### Hierarchy Methods

```tsx
const containerRef = useRef(null)

// Add a child element
const label = new CS.UnityEngine.UIElements.Label()
containerRef.current?.Add(label)

// Insert at index
containerRef.current?.Insert(0, label)

// Remove a child
containerRef.current?.Remove(label)

// Remove by index
containerRef.current?.RemoveAt(0)

// Clear all children
containerRef.current?.Clear()

// Find child index
const index = containerRef.current?.IndexOf(label)
```

### Layout

```tsx
// Force repaint
ref.current?.MarkDirtyRepaint()
```

## Typed Refs

Components export typed element interfaces for better IntelliSense:

```tsx
import type { TextFieldElement, ButtonElement, ScrollViewElement } from "onejs-react"

function Form() {
    const textFieldRef = useRef<TextFieldElement>(null)
    const buttonRef = useRef<ButtonElement>(null)

    const handleSubmit = () => {
        const value = textFieldRef.current?.value
        console.log("Submitted:", value)
    }

    return (
        <View>
            <TextField ref={textFieldRef} placeholder="Enter text" />
            <Button ref={buttonRef} text="Submit" onClick={handleSubmit} />
        </View>
    )
}
```

### Available Element Types

| Type | Specific Properties |
|------|---------------------|
| `VisualElement` | Base type for all elements |
| `TextElement` | `text: string` |
| `LabelElement` | `text: string` |
| `ButtonElement` | `text: string` |
| `TextFieldElement` | `value`, `text`, `isReadOnly`, `maxLength`, `SelectAll()` |
| `ToggleElement` | `value: boolean`, `text: string` |
| `SliderElement` | `value`, `lowValue`, `highValue` |
| `ScrollViewElement` | `scrollOffset`, `ScrollTo(child)` |

## TextField Methods

```tsx
import type { TextFieldElement } from "onejs-react"

function SearchInput() {
    const ref = useRef<TextFieldElement>(null)

    return (
        <View>
            <TextField
                ref={ref}
                placeholder="Search..."
            />
            <Button
                text="Clear"
                onClick={() => {
                    if (ref.current) {
                        ref.current.value = ""
                    }
                }}
            />
            <Button
                text="Select All"
                onClick={() => ref.current?.SelectAll()}
            />
        </View>
    )
}
```

## ScrollView Methods

```tsx
import type { ScrollViewElement, VisualElement } from "onejs-react"

function AutoScroll() {
    const scrollRef = useRef<ScrollViewElement>(null)
    const lastItemRef = useRef<VisualElement>(null)

    const scrollToBottom = () => {
        if (scrollRef.current && lastItemRef.current) {
            scrollRef.current.ScrollTo(lastItemRef.current)
        }
    }

    return (
        <View>
            <ScrollView ref={scrollRef} style={{ height: 300 }}>
                {items.map((item, i) => (
                    <View
                        key={i}
                        ref={i === items.length - 1 ? lastItemRef : null}
                    >
                        <Label text={item} />
                    </View>
                ))}
            </ScrollView>
            <Button text="Scroll to Bottom" onClick={scrollToBottom} />
        </View>
    )
}
```

## Measuring Elements

Access resolved layout values:

```tsx
function MeasuredElement() {
    const ref = useRef(null)
    const [size, setSize] = useState({ width: 0, height: 0 })

    return (
        <View
            ref={ref}
            onGeometryChanged={(e) => {
                setSize({
                    width: e.newRect.width,
                    height: e.newRect.height,
                })
            }}
        >
            <Label text={`Size: ${size.width}x${size.height}`} />
        </View>
    )
}
```

## Direct Style Manipulation

While inline styles are preferred, you can manipulate styles directly:

```tsx
function AnimatedElement() {
    const ref = useRef(null)

    const animate = () => {
        if (ref.current) {
            ref.current.style.backgroundColor = new CS.UnityEngine.Color(1, 0, 0, 1)
        }
    }

    return (
        <View ref={ref} style={{ width: 100, height: 100, backgroundColor: "#333" }}>
            <Button text="Turn Red" onClick={animate} />
        </View>
    )
}
```

## Callback Refs

For more control, use callback refs:

```tsx
function CallbackRefExample() {
    const handleRef = (element) => {
        if (element) {
            console.log("Element mounted:", element.__csType)
            element.AddToClassList("initialized")
        }
    }

    return <View ref={handleRef}>Content</View>
}
```

## Best Practices

1. **Prefer props over refs** - Use refs only when declarative props aren't sufficient
2. **Check for null** - Always check `ref.current` before accessing
3. **Use typed refs** - Import element types for better autocomplete
4. **Avoid frequent direct manipulation** - Let React handle updates when possible

---

<!-- source: https://v3.onejs.com/docs/core-concepts/error-handling -->
<!-- section: Core Concepts -->

# Error Handling

React errors can crash your entire UI. Use `ErrorBoundary` to catch errors and display fallback UI instead.

## Import

```tsx
import { ErrorBoundary } from "onejs-react"
```

## Basic Usage

Wrap components that might throw errors:

```tsx
<ErrorBoundary>
    <MyComponent />
</ErrorBoundary>
```

If `MyComponent` throws an error, ErrorBoundary displays a default error UI instead of crashing.

## Custom Fallback

Provide your own fallback UI:

```tsx
<ErrorBoundary fallback={<Label text="Something went wrong" />}>
    <MyComponent />
</ErrorBoundary>
```

## Fallback with Error Details

Use a function to access error information:

```tsx
<ErrorBoundary
    fallback={(error, errorInfo) => (
        <View style={{ padding: 20, backgroundColor: "#2d1b1b" }}>
            <Label
                text={`Error: ${error.message}`}
                style={{ color: "#ff6666", fontSize: 16 }}
            />
            <Label
                text={errorInfo.componentStack}
                style={{ color: "#ffaaaa", fontSize: 12, marginTop: 10 }}
            />
        </View>
    )}
>
    <MyComponent />
</ErrorBoundary>
```

## Props

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Components to wrap |
| `fallback` | `ReactNode` or `(error, errorInfo) => ReactNode` | Fallback UI |
| `onError` | `(error, errorInfo) => void` | Error callback |
| `onReset` | `() => void` | Reset callback |

## Error Logging

Log errors for debugging or analytics:

```tsx
<ErrorBoundary
    onError={(error, errorInfo) => {
        console.error("React Error:", error.message)
        console.error("Component Stack:", errorInfo.componentStack)

        // Send to error tracking service
        trackError(error, errorInfo)
    }}
>
    <App />
</ErrorBoundary>
```

## Resetting the Boundary

ErrorBoundary can be reset to try rendering again:

```tsx
function App() {
    const boundaryRef = useRef(null)

    return (
        <View>
            <ErrorBoundary
                ref={boundaryRef}
                fallback={
                    <View>
                        <Label text="Error occurred" />
                        <Button
                            text="Try Again"
                            onClick={() => boundaryRef.current?.reset()}
                        />
                    </View>
                }
                onReset={() => {
                    // Clean up any state that caused the error
                    resetAppState()
                }}
            >
                <MainContent />
            </ErrorBoundary>
        </View>
    )
}
```

## Nested Boundaries

Use multiple boundaries for different sections:

```tsx
function App() {
    return (
        <View>
            <ErrorBoundary fallback={<Label text="Header error" />}>
                <Header />
            </ErrorBoundary>

            <ErrorBoundary fallback={<Label text="Content error" />}>
                <MainContent />
            </ErrorBoundary>

            <ErrorBoundary fallback={<Label text="Footer error" />}>
                <Footer />
            </ErrorBoundary>
        </View>
    )
}
```

This way, an error in the header doesn't affect the rest of the app.

## Format Error Utility

The `formatError` helper creates readable error strings:

```tsx
import { ErrorBoundary, formatError } from "onejs-react"

<ErrorBoundary
    fallback={(error, errorInfo) => {
        const formatted = formatError(error, errorInfo.componentStack)
        console.log(formatted)

        return <Label text="Error logged" />
    }}
>
    <MyComponent />
</ErrorBoundary>
```

Output format:

```
Error: Something went wrong

Stack:
  at MyComponent
  at View
  at App

Component:
  at MyComponent
  at ErrorBoundary
  at App
```

## What Errors Are Caught

ErrorBoundary catches:

- Errors in render methods
- Errors in lifecycle methods
- Errors in constructors

ErrorBoundary does **NOT** catch:

- Errors in event handlers (use try/catch)
- Async errors (use try/catch in async functions)
- Errors thrown outside React (global errors)

## Event Handler Errors

Handle errors in event handlers manually:

```tsx
function SafeButton() {
    const handleClick = () => {
        try {
            doSomethingRisky()
        } catch (error) {
            console.error("Click error:", error)
            // Show error to user
        }
    }

    return <Button text="Click" onClick={handleClick} />
}
```

## Async Error Handling

```tsx
function AsyncComponent() {
    const [error, setError] = useState(null)

    useEffect(() => {
        async function loadData() {
            try {
                const data = await fetchData()
                // Use data
            } catch (e) {
                setError(e.message)
            }
        }
        loadData()
    }, [])

    if (error) {
        return <Label text={`Error: ${error}`} style={{ color: "#ff6666" }} />
    }

    return <Label text="Content" />
}
```

## Full App Example

```tsx
import { render, ErrorBoundary, View, Label, Button } from "onejs-react"

function App() {
    return (
        <ErrorBoundary
            fallback={(error) => (
                <View style={{ padding: 40, alignItems: "center" }}>
                    <Label
                        text="Oops! Something went wrong."
                        style={{ fontSize: 20, color: "#ff6666", marginBottom: 20 }}
                    />
                    <Label
                        text={error.message}
                        style={{ color: "#ffaaaa", marginBottom: 20 }}
                    />
                    <Button
                        text="Reload App"
                        onClick={() => location.reload()}
                    />
                </View>
            )}
            onError={(error, info) => {
                // Log to console
                console.error("[App Error]", error)

                // Could send to external service
                // analytics.trackError(error, info)
            }}
        >
            <MainApp />
        </ErrorBoundary>
    )
}

render(<App />, __root)
```

---

<!-- source: https://v3.onejs.com/docs/guides/project-setup -->
<!-- section: Guides -->

# Project Setup

Configure TypeScript, esbuild, and your project structure.

## Default Structure

JSRunner uses the **Scene Folder** convention. When you click **Initialize Project** in JSRunner's inspector, it creates:

```
Assets/Scenes/
└── YourScene/                    # Next to YourScene.unity
    └── MainUI/                   # Named after the GameObject
        ├── ~/                    # Working directory (~ = Unity ignores)
        │   ├── index.tsx         # Entry point
        │   ├── package.json      # Dependencies
        │   ├── tsconfig.json     # TypeScript config
        │   ├── esbuild.config.mjs # Build config
        │   ├── styles/
        │   │   └── main.uss      # Default stylesheet
        │   └── types/
        │       └── global.d.ts   # TypeScript declarations
        ├── PanelSettings.asset   # UI panel configuration
        ├── UIDocument.uxml       # Visual tree asset
        ├── app.js.txt            # Built bundle
        └── app.js.map.txt        # Source map
```

The `~` suffix tells Unity to ignore the working directory. If a folder with the same name already exists, a counter is appended (`MainUI_1`, `MainUI_2`, etc.). Configure scaffolding via the **Default Files** field in JSRunner's inspector.

## Development Workflow

1. Start the watcher:

```bash
npm run watch
```

2. Edit your code, esbuild rebuilds automatically

3. OneJS hot-reloads when it detects the output file changed (works in both edit-mode preview and Play mode)

## package.json

```json
{
    "name": "onejs-app",
    "version": "1.0.0",
    "private": true,
    "type": "module",
    "scripts": {
        "build": "node esbuild.config.mjs",
        "watch": "node esbuild.config.mjs --watch",
        "typecheck": "tsc --noEmit"
    },
    "dependencies": {
        "react": "^19.0.0",
        "onejs-react": "^0.1.0",
        "onejs-unity": "^0.2.0"
    },
    "devDependencies": {
        "@types/react": "^19.0.0",
        "esbuild": "^0.24.0",
        "typescript": "^5.7.0",
        "unity-types": "^6000.3.0"
    }
}
```

- **onejs-react**: React 19 reconciler for OneJS
- **onejs-unity**: esbuild plugins for C# imports, Tailwind, and CSS Modules
- **unity-types**: TypeScript declarations for Unity C# namespaces

## tsconfig.json

```json
{
    "compilerOptions": {
        "target": "ES2022",
        "lib": ["ES2022"],
        "module": "ESNext",
        "moduleResolution": "Bundler",
        "jsx": "react-jsx",
        "strict": true,
        "skipLibCheck": true,
        "noEmit": true,
        "allowJs": true,
        "isolatedModules": true,
        "verbatimModuleSyntax": true,
        "esModuleInterop": true,
        "resolveJsonModule": true,
        "forceConsistentCasingInFileNames": true,
        "baseUrl": ".",
        "paths": {
            "onejs-react": ["./node_modules/onejs-react/src"]
        },
        "types": ["unity-types", "react"]
    },
    "include": ["**/*", "types/**/*.d.ts"],
    "exclude": ["node_modules", "@outputs"]
}
```

The `onejs-react` path mapping points to source files for editor click-through. The `unity-types` package provides type declarations for C# namespaces like `UnityEngine`.

## esbuild.config.mjs

```javascript
import * as esbuild from "esbuild"
import fs from "fs"
import path from "path"
import { fileURLToPath } from "url"
import { importTransformPlugin, tailwindPlugin, ussModulesPlugin } from "onejs-unity/esbuild"

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const isWatch = process.argv.includes("--watch")

// Resolve react to this app's node_modules to prevent duplicate copies
const reactPath = path.resolve(__dirname, "node_modules/react")
const reactJsxPath = path.resolve(__dirname, "node_modules/react/jsx-runtime")
const reactJsxDevPath = path.resolve(__dirname, "node_modules/react/jsx-dev-runtime")

const config = {
    entryPoints: ["index.tsx"],
    bundle: true,
    outfile: "../app.js.txt",
    format: "iife",                // IIFE required for onPlay/onStop lifecycle hooks
    globalName: "__exports",       // Exported functions available as __exports.onPlay, etc.
    target: "es2022",
    jsx: "automatic",
    resolveExtensions: [".tsx", ".ts", ".jsx", ".js", ".json"],
    sourcemap: true,
    alias: {
        "react": reactPath,
        "react/jsx-runtime": reactJsxPath,
        "react/jsx-dev-runtime": reactJsxDevPath,
    },
    packages: "bundle",
    plugins: [
        importTransformPlugin(),                                 // Transform C# imports
        tailwindPlugin({ content: ["./**/*.{tsx,ts,jsx,js}"] }), // Tailwind utilities
        ussModulesPlugin({ generateTypes: true }),               // CSS Modules with .d.ts
    ],
}

// Rename sourcemap to .map.txt for Unity TextAsset compatibility
function renameSourceMap() {
    const oldPath = path.resolve(__dirname, "../app.js.txt.map")
    const newPath = path.resolve(__dirname, "../app.js.map.txt")
    if (fs.existsSync(oldPath)) fs.renameSync(oldPath, newPath)
}

if (isWatch) {
    const ctx = await esbuild.context({
        ...config,
        plugins: [
            ...(config.plugins || []),
            { name: "rename-sourcemap", setup(build) { build.onEnd(() => renameSourceMap()) } }
        ]
    })
    await ctx.watch()
    console.log("Watching for changes...")
} else {
    await esbuild.build(config)
    renameSourceMap()
    console.log("Build complete!")
}
```

Three plugins are included by default:
- **importTransformPlugin**: transforms `import { X } from "UnityEngine"` into `const { X } = CS.UnityEngine`
- **tailwindPlugin**: enables Tailwind utility classes via `import "onejs:tailwind"`
- **ussModulesPlugin**: enables CSS Modules (`.module.uss` files) with auto-generated `.d.ts` type files

## Adding Components

Organize your code into components:

```
YourApp/
├── index.tsx
├── components/
│   ├── Button.tsx
│   ├── Card.tsx
│   └── Header.tsx
├── hooks/
│   └── useGameState.ts
├── styles/
│   └── main.uss
└── utils/
    └── helpers.ts
```

## Path Aliases

For cleaner imports in larger projects, add a `@/*` path alias to your `tsconfig.json`:

```json
"paths": {
    "onejs-react": ["./node_modules/onejs-react/src"],
    "@/*": ["./*"]
}
```

Then use the `@/` prefix:

```tsx
// Instead of
import { Button } from "../../../components/Button"

// Use
import { Button } from "@/components/Button"
```

## Multiple UIs

If your app has distinct screens (menu, HUD, settings), there are two approaches.

### Single app with React state

Handle all screens within one entry point using conditional rendering:

```tsx
function App() {
    const [screen, setScreen] = useState("menu")

    if (screen === "menu") return <Menu onStart={() => setScreen("hud")} />
    if (screen === "hud") return <HUD onPause={() => setScreen("settings")} />
    if (screen === "settings") return <Settings onBack={() => setScreen("hud")} />
}
```

One JSRunner, one bundle, shared state across screens. This is the simplest approach and works well for most apps.

### Separate JSRunner instances

For truly independent UI layers (e.g., a HUD that persists while a menu overlays it), use multiple JSRunners on separate GameObjects, each with its own PanelSettings and working directory:

```
Assets/Scenes/YourScene/
├── HUD/~/                    # JSRunner 1
│   ├── index.tsx
│   └── esbuild.config.mjs
└── Menu/~/                   # JSRunner 2
    ├── index.tsx
    └── esbuild.config.mjs
```

Each JSRunner builds and runs independently with its own JS context. Toggle them by enabling/disabling their GameObjects.

## Environment Variables

Pass build-time values:

```javascript
// esbuild.config.mjs
await esbuild.build({
    ...config,
    define: {
        "process.env.NODE_ENV": isWatch ? '"development"' : '"production"',
        "__DEV__": isWatch.toString(),
    },
})
```

```tsx
// Use in code
if (__DEV__) {
    console.log("Debug mode")
}
```

## Lifecycle Hooks

OneJS supports `onPlay()` and `onStop()` lifecycle hooks. Export them from your entry file to separate game logic from UI setup:

```tsx
import { render, View, Label } from "onejs-react"

function App() {
    return (
        <View style={{ padding: 20 }}>
            <Label>{__isPlaying ? "Playing" : "Edit Mode Preview"}</Label>
        </View>
    )
}

// Module-level: runs in BOTH edit-mode preview and play mode
render(<App />, __root)

// Only called when entering Play mode
export function onPlay() {
    // Spawn GameObjects, start physics, connect to game systems
}

// Only called when exiting Play mode (or before live reload during play)
export function onStop() {
    // Cleanup, save state, disconnect
}
```

**Key points:**
- Module-level code (including `render()`) runs in both edit-mode preview and play mode, so keep it safe for UI preview
- `onPlay()` fires when entering Play mode, or after a live reload during play
- `onStop()` fires when exiting Play mode, or before teardown during a live reload
- `__isPlaying` is a global boolean: `true` in play mode, `false` in edit-mode preview
- The `format: "iife"` and `globalName: "__exports"` in esbuild config are required for lifecycle hooks to work

## Optimizing Builds

For production builds:

```javascript
await esbuild.build({
    ...config,
    minify: true,
    treeShaking: true,
    drop: ["console", "debugger"],
})
```

---

<!-- source: https://v3.onejs.com/docs/guides/building -->
<!-- section: Guides -->

# Building & Deployment

Get your OneJS app running in standalone builds and WebGL.

## How It Works

When you build your Unity project, the `JSRunnerBuildProcessor` runs automatically and handles everything:

1. Locates each JSRunner's `app.js.txt` bundle and assigns it as a TextAsset
2. Copies `assets/` to `StreamingAssets/onejs/assets/` (images, fonts, data files)
3. Extracts [cartridge](/docs/guides/cartridges) files alongside the bundle

**Styles** (CSS Modules and Tailwind) are embedded in the JavaScript bundle, so they work automatically in builds.

## Standalone Builds

Works out of the box. Build normally from **File > Build Settings**.

The JavaScript bundle is stored as a TextAsset alongside your scene:

```
Assets/Scenes/YourScene/
└── App_abc123/
    └── app.js.txt      # TextAsset used in builds
```

In the Editor, JSRunner loads from the filesystem (enabling hot reload). In builds, it uses this TextAsset.

## WebGL Builds

WebGL works with some differences:

- JavaScript runs in the browser's V8/SpiderMonkey engine (JIT compiled, not QuickJS)
- Uses the browser's native `requestAnimationFrame`
- Full browser API access

Build normally and deploy to a web server.

## Assets in Builds

Image and data files from your `assets/` folder are automatically copied to `StreamingAssets/onejs/assets/` during the build. This means `<Image src="logo.png" />` and `loadImage("logo.png")` work identically in Editor and builds.

The destination is flushed before each build, so deleted or renamed files won't linger as stale copies.

See the [Asset Loading](/docs/guides/assets) guide for more details.

## Production Checklist

### Minify Your Code

```javascript
// esbuild.config.mjs
await esbuild.build({
    minify: true,
    treeShaking: true,
    drop: ["console", "debugger"],
})
```

### Test Before Building

Run `npm run build` and verify your app works in the Editor before making a Unity build.

### Check Console

Watch the Unity Console for build processor messages:

```
[JSRunner] Copied 3 asset file(s) to StreamingAssets for: App
[JSRunner] Build preprocessing complete. Processed 1 runner(s), created 1 asset(s), copied 3 asset file(s) to StreamingAssets.
```

## Platform-Specific Code

```tsx
const isWebGL = typeof window !== "undefined"

function App() {
    useEffect(() => {
        if (isWebGL) {
            console.log("Running in browser")
        } else {
            console.log("Running in Unity")
        }
    }, [])
}
```

## Troubleshooting

### "Bundle not found" in Build

- Ensure `npm run build` completed successfully
- Verify `app.js.txt` exists in the instance folder
- Check Unity Console for build processor errors

### "Script error" in WebGL

- Open browser DevTools for the full error message
- Check for CORS issues if loading external resources
- Verify all imports are bundled (not externalized)

### Assets Missing in Build

- Verify files are in the `assets/` folder inside your working directory (`~/`)
- Check the build log for "Copied N asset file(s) to StreamingAssets"
- Ensure the JSRunner is enabled and its GameObject is active

## Size Optimization

Analyze your bundle:

```bash
npx esbuild-visualizer --open
```

Common optimizations:

- Import only what you need from libraries
- Remove unused exports with tree shaking
- Use `drop: ["console"]` in production builds

---

<!-- source: https://v3.onejs.com/docs/guides/css-modules -->
<!-- section: Guides -->

# CSS Modules

CSS Modules provide scoped styling for your components. Class names are automatically hashed to prevent conflicts. Like Tailwind, the styles are embedded in your JavaScript bundle and work in standalone builds.

**Related:** [Styling Basics](/docs/core-concepts/styling) | [Tailwind CSS](/docs/guides/tailwind)

## Setup

Add the esbuild plugin to your config:

```javascript
// esbuild.config.mjs
import { ussModulesPlugin } from "onejs-unity/esbuild"

await esbuild.build({
    // ...
    plugins: [
        ussModulesPlugin({ generateTypes: true }),
    ],
})
```

## Basic Usage

Create a `.module.uss` file:

```css
/* Button.module.uss */
.container {
    padding: 12px 24px;
    border-radius: 8px;
}

.primary {
    background-color: #e94560;
    color: #ffffff;
}

.primary:hover {
    background-color: #ff6b6b;
}
```

Import and use in your component:

```tsx
import { Button } from "onejs-react"
import styles from "./Button.module.uss"

function PrimaryButton({ children, onClick }) {
    return (
        <Button
            className={`${styles.container} ${styles.primary}`}
            onClick={onClick}
        >
            {children}
        </Button>
    )
}
```

## How It Works

The plugin transforms `.module.uss` files at build time:

1. Generates a unique hash from the file path
2. Appends the hash to all class names: `.container` becomes `.container__a1b2c3`
3. Exports a mapping object: `{ container: "container__a1b2c3" }`
4. Calls `compileStyleSheet()` to inject the CSS at runtime

Your component uses the scoped class names, avoiding conflicts with other styles.

## Dynamic Classes

Use bracket notation for dynamic class selection:

```tsx
import styles from "./Button.module.uss"

type Variant = "primary" | "secondary" | "ghost"

function Button({ variant = "primary", children }) {
    const className = `${styles.container} ${styles[variant]}`
    return <Button className={className}>{children}</Button>
}
```

## TypeScript Support

With `generateTypes: true`, the plugin creates `.d.ts` files automatically:

```typescript
// Button.module.uss.d.ts (auto-generated)
declare const styles: {
    readonly "container": string
    readonly "primary": string
    readonly "secondary": string
    readonly "ghost": string
}
export default styles
```

This gives you full autocomplete and type checking for class names.

## Combining Classes

Multiple classes work as expected:

```tsx
<View className={`${styles.card} ${styles.elevated} ${styles.rounded}`}>
    {children}
</View>
```

Combine with conditional classes:

```tsx
<View className={`${styles.button} ${active ? styles.active : ""}`}>
    {children}
</View>
```

## Pseudo-classes

USS pseudo-classes work normally:

```css
/* Input.module.uss */
.input {
    border-width: 1px;
    border-color: #333;
}

.input:hover {
    border-color: #666;
}

.input:focus {
    border-color: #0066cc;
    border-width: 2px;
}
```

The plugin correctly scopes the base class while preserving pseudo-class selectors.

## USS Variables

Custom properties work in `.module.uss` files:

```css
/* Theme.module.uss */
.container {
    --accent: #e94560;
    --text: #ffffff;
    padding: 20px;
}

.title {
    color: var(--accent);
}

.body {
    color: var(--text);
}
```

See [USS Variables](/docs/core-concepts/styling#uss-variables) for full details.

## Global Styles

For global styles that shouldn't be scoped, use regular `.uss` files:

```css
/* global.uss - not scoped */
.unity-button {
    /* Targets Unity's built-in button class */
}
```

Load global styles with `compileStyleSheet()` directly.

## File Structure

Recommended organization:

```
components/
├── Button.tsx
├── Button.module.uss
├── Card.tsx
├── Card.module.uss
└── Input.tsx
└── Input.module.uss
```

## Full Example

```css
/* Card.module.uss */
.card {
    background-color: #1a1a1a;
    border-radius: 8px;
    padding: 20px;
}

.header {
    flex-direction: row;
    justify-content: space-between;
    margin-bottom: 16px;
}

.title {
    font-size: 18px;
    color: #ffffff;
}

.content {
    color: #999999;
}
```

```tsx
import { View, Label } from "onejs-react"
import styles from "./Card.module.uss"

function Card({ title, children }) {
    return (
        <View className={styles.card}>
            <View className={styles.header}>
                <Label text={title} className={styles.title} />
            </View>
            <View className={styles.content}>
                {children}
            </View>
        </View>
    )
}
```

## Hot Reload

CSS Modules work seamlessly with hot reload. Stylesheets are automatically deduplicated by name - when you modify a `.module.uss` file and the app reloads, the existing stylesheet is replaced rather than duplicated.

This happens because each CSS Module uses its file path as the stylesheet name when calling `compileStyleSheet()`. The runtime tracks stylesheets by name and removes any existing stylesheet before adding the updated one.

## Manual Cleanup

If you need to programmatically manage stylesheets:

```tsx
// Remove a specific CSS Module's styles
removeStyleSheet("components/Button.module.uss")

// Remove all JS-loaded stylesheets
clearStyleSheets()
```

See [StyleSheet API](/docs/core-concepts/styling#stylesheet-api) for more details.

---

<!-- source: https://v3.onejs.com/docs/guides/tailwind -->
<!-- section: Guides -->

# Tailwind CSS

OneJS includes a built-in Tailwind-like utility class generator. No external dependencies required - just import and use.

**Related:** [Styling Basics](/docs/core-concepts/styling) | [CSS Modules](/docs/guides/css-modules)

## Setup

Tailwind is enabled by default in the esbuild config. Just add the import to your code:

```tsx
import "onejs:tailwind"
```

That's it! The plugin scans your source files for class names and generates USS automatically.

## Basic Usage

Use Tailwind classes directly:

```tsx
import { render, View, Label, Button } from "onejs-react"
import "onejs:tailwind"

function App() {
    return (
        <View className="p-4 bg-gray-900 rounded-lg">
            <Label className="text-white text-lg" text="Hello" />
            <Button className="mt-2 py-2 px-4 bg-blue-500 hover:bg-blue-600" text="Click" />
        </View>
    )
}

render(<App />, __root)
```

## JIT-Style Generation

Only classes actually used in your source files are included in the bundle. The plugin scans files matching the `content` patterns in your esbuild config:

```javascript
// esbuild.config.mjs
tailwindPlugin({
    content: ["./**/*.{tsx,ts,jsx,js}"]
})
```

Dynamic and conditional classes are fully supported. The scanner extracts string literals from ternaries, logical expressions, and helper functions:

```tsx
// All of these work
<View className={active ? "bg-blue-500" : "bg-gray-500"} />
<View className={clsx("p-4", isActive && "bg-blue-500")} />
<View className={`flex ${size === "lg" ? "px-6" : "px-3"}`} />
```

## Supported Utilities

### Spacing

```tsx
// Padding
<View className="p-4 px-6 py-2 pt-4 pr-6 pb-4 pl-6" />

// Margin
<View className="m-4 mx-auto my-2 mt-4 mr-6 mb-4 ml-6" />
```

> **Note**: USS does not support the `gap` property. Use margins on child elements instead.

### Colors

Full Tailwind color palette: slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.

```tsx
// Background
<View className="bg-gray-900 bg-blue-500 bg-transparent" />

// Text
<Label className="text-white text-gray-300 text-blue-500" />

// Border
<View className="border border-gray-700 border-red-500" />
```

### Layout

```tsx
// Flexbox
<View className="flex flex-row flex-col flex-wrap" />
<View className="justify-center justify-between items-center items-start" />
<View className="flex-1 grow shrink-0" />

// Sizing
<View className="w-full w-1/2 w-64 h-full h-screen" />
<View className="min-w-0 max-w-full min-h-0 max-h-full" />

// Position
<View className="relative absolute top-0 right-0 bottom-0 left-0" />
```

### Typography

```tsx
// Size
<Label className="text-xs text-sm text-base text-lg text-xl text-2xl text-3xl" />

// Weight (maps to -unity-font-style: normal or bold)
<Label className="font-normal font-bold" />

// Alignment
<Label className="text-left text-center text-right" />

// Letter spacing
<Label className="tracking-tight tracking-normal tracking-wide" />
```

> **Note**: USS only supports `-unity-font-style` with `normal`, `bold`, `italic`, and `bold-and-italic`. Classes like `font-thin`, `font-light`, `font-medium` map to `normal`; `font-semibold`, `font-bold`, `font-extrabold`, `font-black` map to `bold`.

### Borders

```tsx
// Width
<View className="border border-2 border-4 border-t border-r border-b border-l" />

// Colors (all sides or individual)
<View className="border border-gray-500" />
<View className="border-t-2 border-t-blue-500" />
<View className="border-b border-b-red-500" />

// Radius
<View className="rounded rounded-sm rounded-md rounded-lg rounded-xl rounded-full" />
<View className="rounded-t-lg rounded-b-none" />
```

### Transforms

```tsx
// Rotate
<View className="rotate-45 rotate-90 -rotate-45" />

// Scale
<View className="scale-50 scale-100 scale-125 hover:scale-105" />
<View className="scale-x-75 scale-y-150" />

// Translate
<View className="translate-x-4 translate-y-2 -translate-x-4" />

// Transform origin
<View className="origin-center origin-top-left origin-bottom-right" />
```

### Transitions

```tsx
// Basic transition
<View className="transition hover:bg-blue-500" />

// With duration and easing
<View className="transition duration-300 ease-in-out hover:scale-105" />

// Specific properties
<View className="transition-colors duration-200" />
<View className="transition-opacity duration-500" />
<View className="transition-transform duration-300" />

// With delay
<View className="transition delay-100 hover:opacity-50" />
```

Duration values: `0`, `75`, `100`, `150`, `200`, `300`, `500`, `700`, `1000` (ms)

### Other

```tsx
// Opacity
<View className="opacity-0 opacity-50 opacity-100" />

// Display
<View className="hidden flex" />

// Overflow
<View className="overflow-hidden overflow-scroll" />

// Flex basis
<View className="basis-1/2 basis-auto basis-0" />

// Aspect ratio
<View className="aspect-square aspect-video" />
```

## Arbitrary Values

Use square brackets for one-off values outside the design system:

```tsx
// Custom sizes
<View className="w-[200] h-[150]" />    // 200px, 150px
<View className="w-[50%] h-[25%]" />    // percentages

// Custom colors
<View className="bg-[#ff5733] text-[#333]" />

// Custom spacing
<View className="p-[15] m-[7]" />       // 15px, 7px

// Custom font size
<Label className="text-[22]" text="Custom size" />

// Custom border radius
<View className="rounded-[10]" />       // 10px
```

Rules:
- Numbers without units default to `px`
- Use `%` for percentages
- Use `#` prefix for hex colors
- No spaces inside brackets

## Character Escaping

Tailwind classes with special characters are automatically escaped for USS:

| Character | Escaped | Example |
|-----------|---------|---------|
| `:` | `_c_` | `hover:bg-red` → `hover_c_bg-red` |
| `/` | `_s_` | `w-1/2` → `w-1_s_2` |
| `.` | `_d_` | `opacity-0.5` → `opacity-0_d_5` |
| `[` `]` | `_lb_` `_rb_` | `w-[100px]` → `w-_lb_100px_rb_` |

Write standard Tailwind in your JSX. The escaping happens automatically at build time.

## Responsive Design

Wrap your app with `ScreenProvider`:

```tsx
import { render, ScreenProvider } from "onejs-react"
import "onejs:tailwind"

render(
    <ScreenProvider>
        <App />
    </ScreenProvider>,
    __root
)
```

Use responsive prefixes:

```tsx
<View className="p-2 sm:p-4 md:p-6 lg:p-8">
    <Label className="text-sm md:text-base lg:text-lg" text="Responsive" />
</View>
```

### Breakpoints

| Prefix | Min Width |
|--------|-----------|
| `sm:` | 640px |
| `md:` | 768px |
| `lg:` | 1024px |
| `xl:` | 1280px |
| `2xl:` | 1536px |

### How It Works

USS doesn't support media queries. Instead:

1. Responsive classes become ancestor-scoped selectors (`.sm .sm_c_p-4`)
2. ScreenProvider adds breakpoint classes to the root element
3. At 1400px width, root has classes: `sm md lg xl`

This enables mobile-first CSS cascading.

## Responsive Hooks

```tsx
import { useBreakpoint, useScreenSize, useResponsive, useMediaQuery } from "onejs-react"

function Component() {
    // Current breakpoint name
    const bp = useBreakpoint() // "base" | "sm" | "md" | "lg" | "xl" | "2xl"

    // Viewport dimensions
    const { width, height } = useScreenSize()

    // All responsive state
    const { isSm, isMd, isLg, isXl, is2xl } = useResponsive()

    // Check specific breakpoint
    const isDesktop = useMediaQuery("lg")

    return (
        <View>
            <Label text={`Breakpoint: ${bp}`} />
            <Label text={`Size: ${width}x${height}`} />
            {isLg && <Label text="Large screen content" />}
        </View>
    )
}
```

## Hover and States

Pseudo-classes work as expected:

```tsx
<View className="bg-gray-800 hover:bg-gray-700">
    <Button className="bg-blue-500 hover:bg-blue-600 active:bg-blue-700" />
</View>
```

## Limitations

USS doesn't support everything in Tailwind:

| Not Supported | Alternative |
|---------------|-------------|
| CSS Grid | Use Flexbox (`flex-row`, `flex-col`) |
| `gap` property | Use margins on children (`mb-4`, `mr-4`) |
| `z-index` | Reorder elements in hierarchy |
| `font-weight` (100-900) | Use `font-normal` or `font-bold` (`-unity-font-style`) |
| `text-transform` | Use rich text tags or C# string methods |
| Shadows | Use background colors or borders |
| Filters | Not available |
| Keyframe animations | Use transitions for simple effects |
| CSS custom properties in utilities | Use [USS Variables](/docs/core-concepts/styling#uss-variables) in a separate `.uss` file |
| `line-height` | Not available in USS |
| `currentColor` | Use explicit colors |
| `:first-child`, `:nth-child` | Not available in USS |

## Full Example

```tsx
import { useState } from "react"
import { render, View, Label, Button, ScreenProvider, useBreakpoint } from "onejs-react"
import "onejs:tailwind"

function Card({ title, children }) {
    return (
        <View className="p-4 md:p-6 bg-gray-800 rounded-lg">
            <Label className="text-lg text-white mb-2" text={title} />
            <View className="text-gray-400">{children}</View>
        </View>
    )
}

function App() {
    const bp = useBreakpoint()

    return (
        <View className="p-4 md:p-8 lg:p-12 bg-gray-900 flex-1">
            <Label className="text-xs text-gray-500 mb-4" text={`Breakpoint: ${bp}`} />

            <View className="flex-col md:flex-row">
                <View className="mb-4 md:mb-0 md:mr-4">
                    <Card title="Feature 1">
                        <Label text="Description here" />
                    </Card>
                </View>
                <Card title="Feature 2">
                    <Label text="Another feature" />
                </Card>
            </View>

            <Button
                className="mt-4 py-2 px-4 bg-blue-500 hover:bg-blue-600 rounded-lg"
                text="Get Started"
            />
        </View>
    )
}

render(
    <ScreenProvider>
        <App />
    </ScreenProvider>,
    __root
)
```

## Hot Reload

Tailwind styles work seamlessly with hot reload. The stylesheet is automatically deduplicated - when you modify your code and the app reloads, the existing Tailwind stylesheet is replaced rather than duplicated.

## esbuild Configuration

Tailwind is enabled by default in the scaffolded esbuild config:

```javascript
import { tailwindPlugin } from "onejs-unity/esbuild"

await esbuild.build({
    plugins: [
        tailwindPlugin({
            content: ["./**/*.{tsx,ts,jsx,js}"],
            safelist: ["bg-blue-500", "bg-red-500"],  // optional
        }),
    ],
})
```

| Option | Description |
|--------|-------------|
| `content` | File patterns to scan for class names |
| `safelist` | Classes to always include, even if not found in source files (useful for classes stored in variables or external data) |

---

<!-- source: https://v3.onejs.com/docs/guides/fetch-api -->
<!-- section: Guides -->

# Fetch API

OneJS provides a `fetch` function for HTTP requests.

## Basic GET Request

```tsx
async function loadData() {
    const response = await fetch("https://api.example.com/data")
    const data = await response.json()
    console.log(data)
}
```

## POST Request

```tsx
async function submitScore(score) {
    const response = await fetch("https://api.example.com/scores", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ score }),
    })

    if (response.ok) {
        console.log("Score submitted!")
    }
}
```

## With React

```tsx
function UserProfile({ userId }) {
    const [user, setUser] = useState(null)
    const [loading, setLoading] = useState(true)
    const [error, setError] = useState(null)

    useEffect(() => {
        async function loadUser() {
            try {
                const res = await fetch(`https://api.example.com/users/${userId}`)
                if (!res.ok) throw new Error("Failed to load user")
                const data = await res.json()
                setUser(data)
            } catch (e) {
                setError(e.message)
            } finally {
                setLoading(false)
            }
        }
        loadUser()
    }, [userId])

    if (loading) return <Label text="Loading..." />
    if (error) return <Label text={`Error: ${error}`} />

    return (
        <View>
            <Label text={user.name} style={{ fontSize: 24 }} />
            <Label text={user.email} style={{ color: "#999" }} />
        </View>
    )
}
```

## Request Options

```tsx
const response = await fetch(url, {
    method: "POST",           // GET, POST, PUT, DELETE, HEAD
    headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer token123",
    },
    body: JSON.stringify(data),
})
```

## Response Methods

```tsx
const response = await fetch(url)

// Get JSON
const json = await response.json()

// Get text
const text = await response.text()

// Check status
if (response.ok) {
    // 200-299
}

console.log(response.status)     // 200
console.log(response.statusText) // "OK"
```

## Error Handling

```tsx
async function fetchWithRetry(url, retries = 3) {
    for (let i = 0; i < retries; i++) {
        try {
            const response = await fetch(url)
            if (!response.ok) {
                throw new Error(`HTTP ${response.status}`)
            }
            return await response.json()
        } catch (error) {
            if (i === retries - 1) throw error
            await new Promise(r => setTimeout(r, 1000 * (i + 1)))
        }
    }
}
```

## Loading States Hook

```tsx
function useFetch(url) {
    const [data, setData] = useState(null)
    const [loading, setLoading] = useState(true)
    const [error, setError] = useState(null)

    useEffect(() => {
        let cancelled = false

        async function load() {
            try {
                setLoading(true)
                const res = await fetch(url)
                const json = await res.json()
                if (!cancelled) setData(json)
            } catch (e) {
                if (!cancelled) setError(e)
            } finally {
                if (!cancelled) setLoading(false)
            }
        }

        load()
        return () => { cancelled = true }
    }, [url])

    return { data, loading, error }
}

// Usage
function LeaderboardScreen() {
    const { data, loading, error } = useFetch("/api/leaderboard")

    if (loading) return <Label text="Loading..." />
    if (error) return <Label text="Failed to load" />

    return (
        <ScrollView>
            {data.map((entry, i) => (
                <Label key={i} text={`${i + 1}. ${entry.name}: ${entry.score}`} />
            ))}
        </ScrollView>
    )
}
```

## Polling

```tsx
function usePolling(url, interval = 5000) {
    const [data, setData] = useState(null)

    useEffect(() => {
        async function poll() {
            const res = await fetch(url)
            const json = await res.json()
            setData(json)
        }

        poll() // Initial fetch
        const id = setInterval(poll, interval)
        return () => clearInterval(id)
    }, [url, interval])

    return data
}
```

## Notes

- Uses Unity's `UnityWebRequest` under the hood
- Works in Editor, Standalone, and WebGL builds
- CORS restrictions may apply in WebGL
- For local development, ensure your API server allows cross-origin requests

---

<!-- source: https://v3.onejs.com/docs/guides/websocket -->
<!-- section: Guides -->

# WebSocket

OneJS provides the standard `WebSocket` API for persistent, bidirectional communication with servers. Unlike [fetch](/docs/guides/fetch-api) which is request-response, WebSocket keeps a connection open for continuous data exchange.

## Basic Usage

```tsx
const ws = new WebSocket("wss://echo.example.com")

ws.onopen = () => {
    ws.send("Hello server")
    ws.send(JSON.stringify({ type: "subscribe", channel: "scores" }))
}

ws.onmessage = (event) => {
    console.log("Received:", event.data)
}

ws.onclose = (event) => {
    console.log("Closed:", event.code, event.reason)
}

ws.onerror = () => {
    console.error("WebSocket error")
}
```

Check `readyState` before sending outside of `onopen`:

```tsx
if (ws.readyState === WebSocket.OPEN) {
    ws.send("safe to send")
}
```

## Binary Data

Send and receive binary data using `ArrayBuffer` or `TypedArray`:

```tsx
ws.onopen = () => {
    const bytes = new Uint8Array([0x01, 0x02, 0x03])
    ws.send(bytes)

    // TypedArray subviews send only the viewed portion
    const large = new Uint8Array([0, 1, 2, 3, 4, 5])
    const slice = new Uint8Array(large.buffer, 2, 3) // bytes [2, 3, 4]
    ws.send(slice) // sends only 3 bytes, not the whole buffer
}

ws.onmessage = (event) => {
    if (event.data instanceof ArrayBuffer) {
        const view = new Uint8Array(event.data)
        console.log("Binary:", view[0], view[1])
    } else {
        console.log("Text:", event.data)
    }
}
```

Incoming binary frames are always delivered as `ArrayBuffer` (`binaryType` defaults to `"arraybuffer"`).

## Subprotocols

Pass one or more subprotocols to negotiate with the server:

```tsx
const ws = new WebSocket("wss://example.com/graphql", "graphql-ws")

ws.onopen = () => {
    console.log("Negotiated protocol:", ws.protocol) // "graphql-ws"
}
```

After the connection opens, `ws.protocol` contains the server-selected subprotocol (or an empty string if none was negotiated).

## Connection States

| Constant | Value | Description |
|----------|-------|-------------|
| `CONNECTING` | 0 | Connection in progress |
| `OPEN` | 1 | Connected and ready to send |
| `CLOSING` | 2 | Close initiated |
| `CLOSED` | 3 | Connection closed |

Constants are accessible on both the class (`WebSocket.OPEN`) and instances (`ws.OPEN`).

## With React

Store the connection in a ref to send messages, and clean up on unmount:

```tsx
function Chat({ serverUrl }) {
    const [messages, setMessages] = useState([])
    const wsRef = useRef(null)

    useEffect(() => {
        const ws = new WebSocket(serverUrl)
        wsRef.current = ws

        ws.onmessage = (event) => {
            const msg = JSON.parse(event.data)
            setMessages((prev) => [...prev, msg])
        }

        return () => ws.close()
    }, [serverUrl])

    function send(text) {
        if (wsRef.current?.readyState === WebSocket.OPEN) {
            wsRef.current.send(JSON.stringify({ text }))
        }
    }

    return (
        <View>
            <ScrollView style={{ flexGrow: 1 }}>
                {messages.map((msg, i) => (
                    <Label key={i} text={msg.text} />
                ))}
            </ScrollView>
            <Button text="Send" onClick={() => send("Hello!")} />
        </View>
    )
}
```

For automatic reconnection, wrap the logic in a hook:

```tsx
function useWebSocket(url) {
    const [lastMessage, setLastMessage] = useState(null)
    const wsRef = useRef(null)
    const reconnectTimer = useRef(null)

    function connect() {
        const ws = new WebSocket(url)
        wsRef.current = ws

        ws.onmessage = (event) => {
            setLastMessage(event.data)
        }

        ws.onclose = () => {
            reconnectTimer.current = setTimeout(connect, 3000)
        }
    }

    useEffect(() => {
        connect()
        return () => {
            clearTimeout(reconnectTimer.current)
            wsRef.current?.close()
        }
    }, [url])

    function send(data) {
        if (wsRef.current?.readyState === WebSocket.OPEN) {
            wsRef.current.send(data)
        }
    }

    return { lastMessage, send }
}
```

## Notes

- Full `EventTarget` interface: `addEventListener`, `removeEventListener`, and `dispatchEvent`, alongside `on*` handler properties
- Event objects include `target` and `currentTarget` set to the WebSocket instance
- Uses `ClientWebSocket` on native platforms; browser's native WebSocket on WebGL
- Connections are automatically cleaned up on live reload

---

<!-- source: https://v3.onejs.com/docs/guides/assets -->
<!-- section: Guides -->

# Asset Loading

Load images, fonts, and data files from your project. Path resolution between Editor and builds is handled automatically.

## Quick Start

Place files in `assets/` inside your working directory, then load by relative path:

```
~/                             <- Working directory
├── assets/
│   ├── logo.png
│   ├── fonts/
│   │   └── Inter.ttf
│   └── data/
│       └── config.json
├── index.tsx
└── esbuild.config.mjs
```

```typescript
import { loadImage, loadFont, loadJson } from "onejs-unity/assets"

const logo = loadImage("logo.png")
const font = loadFont("fonts/Inter.ttf")
const config = loadJson("data/config.json")
```

## Functions

| Function | Returns | Description |
|----------|---------|-------------|
| `loadImage(path)` | `Texture2D | VectorImage` | Load PNG, JPG, or SVG. Accepts relative or absolute paths |
| `loadImageFromUrl(url)` | `Promise<Texture2D>` | Load an image from a URL |
| `loadFont(path)` | `Font` | Load a font file (TTF, OTF) |
| `loadFontDefinition(path)` | `FontDefinition` | Load a font for UI Toolkit styling |
| `loadText(path)` | `string` | Load a text file |
| `loadJson<T>(path)` | `T` | Load and parse JSON |
| `loadBytes(path)` | `Uint8Array` | Load raw bytes |
| `assetExists(path)` | `boolean` | Check if an asset exists |
| `getAssetPath(path)` | `string` | Get the resolved full path |

All file-based functions are **synchronous** and throw if not found. `loadImageFromUrl` is async. Paths are case-sensitive on most platforms.

## Using with Components

The `<Image>` component's `src` prop loads from the assets folder:

```tsx
import { Image } from "onejs-react"

<Image src="hero.png" style={{ width: 200, height: 200 }} />
```

For background images and custom fonts, use the load functions:

```tsx
import { loadImage, loadFontDefinition } from "onejs-unity/assets"

<View style={{ backgroundImage: loadImage("bg.png"), width: 300, height: 200 }} />

<Label style={{ unityFontDefinition: loadFontDefinition("fonts/Inter.ttf") }}>
    Custom font text
</Label>
```

## Absolute Paths and URLs

For files outside the `assets/` folder (user save directories, Steam Workshop cache, remote servers), use absolute paths or URLs.

### Absolute Paths

All load functions accept absolute file paths. Asset resolution is bypassed entirely:

```tsx
import { loadImage } from "onejs-unity/assets"

const thumb = loadImage("/path/to/steam/workshop/thumbnail.png")

// Works with <Image> src prop too
<Image src="/path/to/user/saves/preview.png" style={{ width: 128, height: 128 }} />

// Works with backgroundImage
<View style={{ backgroundImage: loadImage("/path/to/bg.png"), width: 300, height: 200 }} />
```

### URLs

`loadImageFromUrl` loads remote images. Returns a `Promise<Texture2D>`:

```tsx
import { loadImageFromUrl } from "onejs-unity/assets"

const tex = await loadImageFromUrl("https://example.com/thumbnail.jpg")
<Image image={tex} style={{ width: 128, height: 128 }} />
```

> **Note:** Textures from absolute paths or URLs are not cached. Cache the `Texture2D` yourself if loading repeatedly, and call `Object.Destroy()` when done to avoid memory leaks.

## Path Resolution

In the **Editor**, assets load from the filesystem. In **builds**, from `StreamingAssets`.

| Context | Resolved path for `logo.png` |
|---------|------------------------------|
| Editor | `{WorkingDir}/assets/logo.png` |
| Build | `{StreamingAssets}/onejs/assets/logo.png` |

This is automatic. Absolute paths bypass resolution entirely.

## Builds

Assets are copied to `StreamingAssets` automatically during Unity builds via `JSRunnerBuildProcessor`:

1. Finds each JSRunner's working directory
2. Copies `{WorkingDir}/assets/` to `Assets/StreamingAssets/onejs/assets/`
3. Skips `.meta` files
4. Flushes the destination first to remove stale files

No esbuild plugin or manual setup needed.

## Unity Resources

For assets that need Unity's import pipeline, use the `Resources/` folder instead. Place files in `Assets/Resources/` and Unity imports them as native types.

```tsx
import { Image } from "onejs-react"
import { VectorImage } from "UnityEngine/UIElements"

const icon = CS.UnityEngine.Resources.Load("icon", VectorImage)
<Image image={icon} style={{ width: 64, height: 64 }} />
```

Path is relative to any `Resources/` folder, without file extension.

### `assets/` vs `Resources/`

| | `assets/` folder | `Resources/` folder |
|--|------------------|---------------------|
| **Location** | `{WorkingDir}/assets/` | `Assets/Resources/` |
| **Loading** | `loadImage()`, `loadFont()`, etc. | `Resources.Load()` |
| **Processing** | Raw files, read at runtime | Unity-imported at build time |
| **Best for** | Images, fonts, JSON, text data | Assets needing Unity import processing |

Most of the time `assets/` is all you need.

### Async Resource Loading

Load Unity resources without blocking:

```typescript
import { loadResourceAsync } from "onejs-unity/assets"

const textAsset = await loadResourceAsync("MyData/config", CS.UnityEngine.TextAsset)
console.log(textAsset.text)

// Returns null if not found
const missing = await loadResourceAsync("DoesNotExist")
```

With React:

```tsx
function ConfigPanel() {
    const [config, setConfig] = useState(null)

    useEffect(() => {
        let cancelled = false
        async function load() {
            const asset = await loadResourceAsync("GameConfig", CS.UnityEngine.TextAsset)
            if (!cancelled && asset) {
                setConfig(JSON.parse(asset.text))
            }
        }
        load()
        return () => { cancelled = true }
    }, [])

    if (!config) return <Label text="Loading..." />
    return <Label text={`Difficulty: ${config.difficulty}`} />
}
```

| | `loadImage` / `loadText` | `loadResourceAsync` |
|--|--------------------------|---------------------|
| **Source** | `assets/` folder (raw files) | Unity `Resources/` folder |
| **Sync/Async** | Synchronous | Asynchronous (Promise) |
| **Asset processing** | Raw bytes/text at runtime | Unity-imported at build time |
| **Not found** | Throws error | Returns `null` |

## Package Assets

npm packages can distribute assets using the `@namespace/` convention:

```
my-ui-kit/
├── package.json
├── assets/
│   └── @my-ui-kit/
│       ├── icons/
│       │   └── check.png
│       └── backgrounds/
│           └── gradient.png
└── src/
    └── index.ts
```

Load with the `@` prefix:

```typescript
const icon = loadImage("@my-ui-kit/icons/check.png")
```

In the Editor, assets resolve through `node_modules`. In builds, they're copied to `StreamingAssets/onejs/assets/@my-ui-kit/`.

To generate the manifest for Editor resolution, add `copyAssetsPlugin` to your esbuild config:

```javascript
import { copyAssetsPlugin } from "onejs-unity/esbuild"

const config = {
    plugins: [
        copyAssetsPlugin(),
    ],
}
```

---

<!-- source: https://v3.onejs.com/docs/guides/web-apis -->
<!-- section: Guides -->

# Web APIs

OneJS provides browser-compatible APIs so JavaScript libraries and patterns work as expected. These are implemented using Unity's underlying systems.

## localStorage

Persist data using Unity's PlayerPrefs:

```tsx
// Store data
localStorage.setItem("username", "player1")
localStorage.setItem("settings", JSON.stringify({ volume: 0.8 }))

// Retrieve data
const username = localStorage.getItem("username") // "player1"
const settings = JSON.parse(localStorage.getItem("settings"))

// Remove data
localStorage.removeItem("username")

// Clear all data
localStorage.clear()
```

### Limitations

Unlike browser localStorage:

- `localStorage.key(index)` always returns `null` (PlayerPrefs doesn't support enumeration)
- `localStorage.length` always returns `0`
- Data persists permanently (no expiration)

### Example: Saving Game State

```tsx
function usePersistentState(key, defaultValue) {
    const [value, setValue] = useState(() => {
        const stored = localStorage.getItem(key)
        return stored ? JSON.parse(stored) : defaultValue
    })

    useEffect(() => {
        localStorage.setItem(key, JSON.stringify(value))
    }, [key, value])

    return [value, setValue]
}

function Settings() {
    const [volume, setVolume] = usePersistentState("volume", 1.0)

    return (
        <Slider
            value={volume}
            lowValue={0}
            highValue={1}
            onChange={(e) => setVolume(e.value)}
        />
    )
}
```

## sessionStorage

`sessionStorage` is an alias to `localStorage` in OneJS. Unity doesn't have browser-style sessions, so data persists across app restarts.

If you need session-scoped data, clear on app start:

```tsx
// At app initialization
const SESSION_KEY = "__session_id"
const currentSession = Date.now().toString()
const lastSession = localStorage.getItem(SESSION_KEY)

if (lastSession !== currentSession) {
    // Clear session data from previous run
    localStorage.removeItem("temp_data")
    localStorage.setItem(SESSION_KEY, currentSession)
}
```

## URL & URLSearchParams

Parse and manipulate URLs:

```tsx
// Parse a URL
const url = new URL("https://api.example.com:8080/users?page=1&limit=10#section")

console.log(url.hostname)  // "api.example.com"
console.log(url.port)      // "8080"
console.log(url.pathname)  // "/users"
console.log(url.search)    // "?page=1&limit=10"
console.log(url.hash)      // "#section"
console.log(url.origin)    // "https://api.example.com:8080"

// Modify URL
url.pathname = "/posts"
url.searchParams.set("page", "2")
console.log(url.href)  // "https://api.example.com:8080/posts?page=2&limit=10#section"
```

### URLSearchParams

Work with query strings:

```tsx
// Create from string
const params = new URLSearchParams("foo=1&bar=2")

// Get values
params.get("foo")      // "1"
params.getAll("foo")   // ["1"]
params.has("bar")      // true

// Modify
params.set("foo", "new")
params.append("baz", "3")
params.delete("bar")

// Iterate
params.forEach((value, key) => {
    console.log(`${key}: ${value}`)
})

// Convert to string
params.toString()  // "foo=new&baz=3"
```

### API Request Helper

```tsx
function buildApiUrl(endpoint, params = {}) {
    const url = new URL(endpoint, "https://api.example.com")

    Object.entries(params).forEach(([key, value]) => {
        url.searchParams.set(key, value)
    })

    return url.href
}

// Usage
const url = buildApiUrl("/users", { page: 1, limit: 20 })
// "https://api.example.com/users?page=1&limit=20"
```

## Base64 Encoding

Encode and decode Base64:

```tsx
// Encode string to Base64
const encoded = btoa("Hello, World!")
console.log(encoded)  // "SGVsbG8sIFdvcmxkIQ=="

// Decode Base64 to string
const decoded = atob("SGVsbG8sIFdvcmxkIQ==")
console.log(decoded)  // "Hello, World!"
```

### Use Cases

```tsx
// Encode JSON for URL-safe transmission
const data = { id: 123, name: "test" }
const encoded = btoa(JSON.stringify(data))

// Basic auth header
const credentials = btoa(`${username}:${password}`)
const headers = { Authorization: `Basic ${credentials}` }
```

## Timers

Standard JavaScript timing functions:

```tsx
// One-time delay
const timeoutId = setTimeout(() => {
    console.log("Executed after 1 second")
}, 1000)

clearTimeout(timeoutId)  // Cancel

// Repeated interval
const intervalId = setInterval(() => {
    console.log("Every 500ms")
}, 500)

clearInterval(intervalId)  // Stop

// Immediate execution (microtask)
const immediateId = setImmediate(() => {
    console.log("Runs immediately after current code")
})

clearImmediate(immediateId)  // Cancel

// Animation frame (synced with Unity Update)
function animate() {
    // Update animation
    requestAnimationFrame(animate)
}
const rafId = requestAnimationFrame(animate)
cancelAnimationFrame(rafId)  // Stop
```

### React Timer Patterns

```tsx
// Interval hook
function useInterval(callback, delay) {
    const savedCallback = useRef(callback)

    useEffect(() => {
        savedCallback.current = callback
    }, [callback])

    useEffect(() => {
        if (delay === null) return

        const id = setInterval(() => savedCallback.current(), delay)
        return () => clearInterval(id)
    }, [delay])
}

// Usage
function Clock() {
    const [time, setTime] = useState(new Date())

    useInterval(() => {
        setTime(new Date())
    }, 1000)

    return <Label text={time.toLocaleTimeString()} />
}
```

## performance.now()

High-precision timestamp for performance measurement:

```tsx
const start = performance.now()

// Do work
expensiveOperation()

const end = performance.now()
console.log(`Took ${end - start}ms`)
```

**Note:** In WebGL, this is the native browser API. On other platforms, it returns the time since JavaScript started.

## queueMicrotask

Schedule code to run after current task but before rendering:

```tsx
queueMicrotask(() => {
    console.log("Runs after current synchronous code")
})
console.log("This logs first")
```

Useful for batching updates:

```tsx
let pendingUpdates = []
let scheduled = false

function scheduleUpdate(update) {
    pendingUpdates.push(update)

    if (!scheduled) {
        scheduled = true
        queueMicrotask(() => {
            const updates = pendingUpdates
            pendingUpdates = []
            scheduled = false

            // Process all batched updates
            updates.forEach(u => u())
        })
    }
}
```

## StyleSheet APIs

See [Styling - StyleSheet API](/docs/core-concepts/styling#stylesheet-api) for runtime stylesheet management (`loadStyleSheet`, `compileStyleSheet`, `removeStyleSheet`, `clearStyleSheets`).

## Platform Differences

| API | Native (QuickJS) | WebGL (Browser) |
|-----|------------------|-----------------|
| `localStorage` | PlayerPrefs | Native localStorage |
| `fetch` | UnityWebRequest | Native fetch |
| `WebSocket` | C# ClientWebSocket | Native WebSocket |
| `URL` | Polyfill | Native URL |
| `performance.now()` | JS engine time | Native high-res time |
| `setTimeout` | Unity Update loop | Native timers |
| `requestAnimationFrame` | Unity Update loop | Native RAF |

The same code works on both platforms. OneJS uses native browser APIs in WebGL for better performance.

---

<!-- source: https://v3.onejs.com/docs/guides/state-sync -->
<!-- section: Guides -->

# C# State Sync

React doesn't know when C# values change. OneJS provides two hooks to sync C# state into React components.

| | `useFrameSync` | `useEventSync` |
|--|----------------|----------------|
| **How it works** | Polls every frame, re-renders on change | Subscribes to C# events, reads on fire |
| **C# requirements** | Just a property | Property + `event Action` + `Invoke()` |
| **Per-frame cost** | 1 proxy read (zero with FastPath) | Zero |
| **Best for** | Simple primitives, Unity built-ins | Collections, complex/derived state |


Start with `useFrameSync` for most properties. It's more ergonomic (no events to declare or fire), less error-prone (can't forget to invoke an event), and zero-alloc with FastPath.

Switch to `useEventSync` when you have collections (avoids per-frame `toArray()`), many properties that rarely change, or C# code that already fires events.

```tsx
import { useFrameSync, useEventSync, toArray } from "onejs-react"
```

## useFrameSync

Polls a C# value every frame and re-renders when it changes. Simplest way to read C# state. No C# events needed.

### Simple Mode

For primitives (numbers, strings, booleans), pass a getter. Re-renders when the value changes (`Object.is` comparison):

```tsx
const health = useFrameSync(() => player.Health)
const gold = useFrameSync(() => player.Gold)
const name = useFrameSync(() => target?.name ?? "Unknown")
```

With [FastPath](/docs/guides/zero-alloc) registered, simple mode is **zero-allocation** per frame. No C# boilerplate required, just a property.

### Selector Mode

C# objects always return the **same proxy reference** (cached by handle), so `Object.is` would always return `true`. Pass a **selector** as the second argument to extract comparable primitives:

```tsx
const place = useFrameSync(
    () => gameState.currentPlace,
    (p) => [p?.Name, p?.NPCs?.Count]
)
```

Each frame, the selector's output is compared element-by-element. If any value changed, the component re-renders. The returned object is always fresh from the getter.

This works with any C# object (game state, Unity structs, quest data):

```tsx
// Structs: extract the fields you care about
const pos = useFrameSync(
    () => player.transform.position,
    (p) => [p?.x, p?.y, p?.z]
)

// Version stamp: catch any change with a single selector
const quest = useFrameSync(
    () => questManager.activeQuest,
    (q) => [q?.Version]
)
```

> **Note:** Selector mode allocates a new array every frame for comparison, even when nothing changed. For complex state with many selectors, consider `useEventSync` instead.

### Collections and the Parent/Child Pattern

C# collections (`List<T>`, arrays) have `.Count` and indexers but no `.map()` or `.filter()`. Use `toArray` to convert them to JS arrays:

```tsx
const items = toArray(inventory) // reads .Count, loops indexer, returns JS array
```

For lists with mutable items (inventories, NPC lists, quest logs), split into a **parent** that watches list structure and **children** that each watch their own item:

- **Parent** selects `[collection.Count]`: re-renders only on add/remove
- **Child** selects `[item.Name, item.Durability, ...]`: re-renders only when that item changes

When one item's durability drops, only that child re-renders. The parent and all other children are untouched. When an item is added or removed, the parent re-renders and mounts/unmounts the affected child.

### Full Example

A complete example showing all three patterns together: primitives, selectors, and the parent/child collection pattern.

**C# component:**

```csharp
using System.Collections.Generic;
using UnityEngine;

namespace MyGame {
    public class Item {
        public int Id { get; set; }
        public string Name { get; set; }
        public int Durability { get; set; }
        public int StackCount { get; set; }
        public int Version { get; set; }
    }

    public class PlayerController : MonoBehaviour {
        public int Health { get; set; } = 100;
        public int Gold { get; set; } = 50;
        public List<Item> Inventory { get; set; } = new() {
            new Item { Id = 1, Name = "Sword", Durability = 100, StackCount = 1, Version = 1 },
            new Item { Id = 2, Name = "Shield", Durability = 80, StackCount = 1, Version = 1 },
            new Item { Id = 3, Name = "Potion", Durability = 1, StackCount = 5, Version = 1 },
        };
    }
}
```

> Both C# properties (`{ get; set; }`) and plain fields work. The proxy tries properties first, then falls back to fields.

**TypeScript UI:**

```tsx
import React from "react"
import { View, Text, ScrollView, render } from "onejs-react"
import { useFrameSync, toArray } from "onejs-react"

interface Item {
    Id: number
    Name: string
    Durability: number
    StackCount: number
    Version: number
}

interface PlayerController {
    Health: number
    Gold: number
    Inventory: { Count: number; [index: number]: Item }
}

// Cache reference at module scope, don't call Find() inside a getter
const player = CS.UnityEngine.GameObject.Find("Player")
    ?.GetComponent("MyGame.PlayerController") as unknown as PlayerController | null

// --- Child: only re-renders when THIS item's properties change ---
const ItemSlot = React.memo(function ItemSlot({ item }: { item: Item }) {
    const data = useFrameSync(
        () => item,
        (i) => [i.Name, i.Durability, i.StackCount]
    )

    return (
        <View style={{ flexDirection: "row", padding: 4 }}>
            <Text style={{ color: "#fff" }}>
                {data.Name} x{data.StackCount} ({data.Durability} dur)
            </Text>
        </View>
    )
})

// --- Parent: only re-renders when items are added/removed ---
function InventoryPanel() {
    const inv = useFrameSync(
        () => player?.Inventory ?? null,
        (i) => [i?.Count]
    )

    if (!inv) return <Text style={{ color: "#666" }}>No inventory</Text>

    return (
        <ScrollView>
            {toArray<Item>(inv).map(item => (
                <ItemSlot key={item.Id} item={item} />
            ))}
        </ScrollView>
    )
}

// --- App: primitives use simple mode ---
function App() {
    const health = useFrameSync(() => player?.Health ?? 0)
    const gold = useFrameSync(() => player?.Gold ?? 0)

    return (
        <View style={{ padding: 16, backgroundColor: "#1a1a1a" }}>
            <Text style={{ color: "#4ade80", fontSize: 18 }}>HP: {health}</Text>
            <Text style={{ color: "#fbbf24", fontSize: 18 }}>Gold: {gold}</Text>
            <Text style={{ color: "#888", marginTop: 16, marginBottom: 8 }}>
                Inventory:
            </Text>
            <InventoryPanel />
        </View>
    )
}

render(<App />, __root)
```

If your C# items use a version stamp (e.g., via Fody), the child selector can be simplified to `(i) => [i.Version]` to catch any property change.

This pattern scales to any nested structure: places with NPCs, quest logs with objectives, skill trees with nodes.

## useEventSync

Subscribes to C# events instead of polling. Zero work when nothing changes. Use this when:

- Your C# code already fires events on state change
- You have collections that are expensive to poll (avoids per-frame `toArray`)
- You have many properties that rarely change

### Convention Form

Pass the source object and property name. Subscribes to `On{Prop}Changed` and reads the property automatically:

```tsx
const health = useEventSync(player, "Health")
const score = useEventSync(player, "Score")
```

C# side needs standard events:

```csharp
public class Character : MonoBehaviour {
    float _health = 100f;
    public float Health => _health;
    public event Action OnHealthChanged;

    public void TakeDamage(float amount) {
        _health -= amount;
        OnHealthChanged?.Invoke();
    }
}
```

No source generators, no special base classes.

### Explicit Form

For derived state or multiple event sources, pass a getter and an array of `[source, eventName]` pairs:

```tsx
const itemCount = useEventSync(
    () => inventory.Items.Count,
    [[inventory, "OnItemAdded"], [inventory, "OnItemRemoved"]]
)
```

Works with static events too:

```tsx
const score = useEventSync(
    () => CS.MyGame.GameManager.Score,
    [[CS.MyGame.GameManager, "OnScoreChanged"]]
)
```

## Choosing Between Them

| | `useFrameSync` | `useEventSync` |
|--|----------------|----------------|
| C# boilerplate | Just a property | Property + event + Invoke() |
| JS boilerplate | One line | One line |
| Per-frame cost | 1 proxy read (zero with FastPath) | Zero |
| Best for | Simple primitives, Unity built-ins, third-party types | Collections, complex state, event-driven architectures |


For a typical game UI:

- **Player stats** (health, gold, score): `useFrameSync`. Simplest, zero-alloc with FastPath.
- **Inventory list**: `useEventSync`. Avoids per-frame collection traversal.
- **Transform position**: `useFrameSync`. No events on Transform, already FastPath-registered.
- **Quest state**: `useEventSync`. Complex state, fires events on quest progress.

## Performance

`useFrameSync` simple mode with [FastPath](/docs/guides/zero-alloc) is **zero-allocation** per frame. For most simple properties, it's the right default.

Selector mode allocates a new array every frame for comparison. With many selectors at 60fps, this adds up. Switch to `useEventSync` if you see GC pressure in the Unity Profiler.

### FastPath Registration

Common Unity types (`Transform`, `Time`, `GameObject`, etc.) are pre-registered. For your own types:

```csharp
// Register once (e.g., in Awake or RuntimeInitializeOnLoadMethod)
QuickJSNative.FastPath.Property<PlayerController, int>("Health", p => p.Health);
QuickJSNative.FastPath.Property<PlayerController, int>("Gold", p => p.Gold);
QuickJSNative.FastPath.Property<PlayerController, float>("Speed", p => p.Speed, (p, v) => p.Speed = v);
```

No JavaScript changes needed. The same `useFrameSync(() => player.Health)` call now hits the fast path automatically.

See [Zero-Allocation Interop](/docs/guides/zero-alloc) for the full details.

## Reference

### useThrottledSync

Polls at a custom interval instead of every frame:

```tsx
import { useThrottledSync } from "onejs-react"

const gameTime = useThrottledSync(() => gameManager.GameTime, 1000)  // every 1s
const score = useThrottledSync(() => gameManager.Score, 250)         // every 250ms
```

### Dependencies

All sync hooks accept an optional `deps` array as the last argument, for when the source reference can change:

```tsx
const health = useFrameSync(() => currentPlayer.Health, [currentPlayer])
const score = useEventSync(currentPlayer, "Score", [currentPlayer])

const place = useFrameSync(
    () => currentPlayer.Location,
    (loc) => [loc?.Name],
    [currentPlayer]
)
```

### TypeScript Declarations

Define interfaces for your C# types in a `.d.ts` file:

```tsx
// types/game.d.ts
declare namespace CS.MyGame {
    interface Item {
        readonly Id: number
        readonly Name: string
        readonly Durability: number
        readonly StackCount: number
        readonly Version: number
    }

    interface PlayerController {
        readonly Health: number
        readonly Gold: number
        readonly Inventory: { Count: number; [index: number]: Item }
    }
}
```

---

<!-- source: https://v3.onejs.com/docs/guides/async-csharp -->
<!-- section: Guides -->

# Async C# Methods

C# `async Task` methods automatically become JavaScript Promises. You can `await` them just like any other async operation.

## Basic Usage

```csharp
// C#
public static class DataLoader {
    public static async Task<string> LoadDataAsync(string url) {
        using var request = UnityWebRequest.Get(url);
        await request.SendWebRequest();
        return request.downloadHandler.text;
    }
}
```

```javascript
// JavaScript
const data = await CS.DataLoader.LoadDataAsync("/api/data")
console.log(data)
```

Non-generic `Task` methods work the same way:

```csharp
// C#
public static async Task SaveAsync(string path, string content) {
    await File.WriteAllTextAsync(path, content);
}
```

```javascript
// JavaScript
await CS.DataLoader.SaveAsync("save.json", JSON.stringify(state))
// resolves to null (no return value)
```

## Return Types

| C# Return Type | JavaScript Result |
|---------------|-------------------|
| `Task` | `null` |
| `Task<int>`, `Task<float>`, `Task<bool>` | `number`, `number`, `boolean` |
| `Task<string>` | `string` |
| `Task<T>` (reference type) | C# proxy object |
| Already-completed `Task<T>` | Returns result directly (not a Promise) |

Already-completed tasks (e.g., `Task.FromResult(42)`) skip the Promise path entirely and return the result synchronously.

## Error Handling

Faulted and canceled tasks reject the Promise, so use standard `try/catch`:

```csharp
// C#
public static class Api {
    public static async Task<string> FetchUserAsync(int id) {
        var user = await db.FindAsync(id);
        if (user == null) throw new Exception("User not found");
        return user.Name;
    }

    public static async Task<string> SlowQueryAsync(CancellationToken ct) {
        await Task.Delay(5000, ct);
        return "done";
    }
}
```

```javascript
// JavaScript
try {
    const name = await CS.Api.FetchUserAsync(999)
} catch (e) {
    console.log(e.message) // "User not found"
}
```

Canceled tasks reject with `"Task was canceled"`:

```javascript
try {
    const result = await CS.Api.SlowQueryAsync(token)
} catch (e) {
    console.log(e.message) // "Task was canceled"
}
```

## With React

Use the standard `useEffect` + async pattern for loading data from C# async methods:

```tsx
import { View, Label, render } from "onejs-react"
import { useState, useEffect } from "react"

function PlayerStats({ playerId }) {
    const [stats, setStats] = useState(null)
    const [loading, setLoading] = useState(true)
    const [error, setError] = useState(null)

    useEffect(() => {
        let cancelled = false

        async function load() {
            try {
                const result = await CS.MyGame.StatsManager.GetStatsAsync(playerId)
                if (!cancelled) setStats(result)
            } catch (e) {
                if (!cancelled) setError(e.message)
            } finally {
                if (!cancelled) setLoading(false)
            }
        }

        load()
        return () => { cancelled = true }
    }, [playerId])

    if (loading) return <Label text="Loading..." />
    if (error) return <Label text={`Error: ${error}`} />

    return (
        <View>
            <Label text={`Level: ${stats.Level}`} />
            <Label text={`Score: ${stats.Score}`} />
        </View>
    )
}
```

## How It Works

When you call a C# async method from JavaScript:

1. If the task is **already completed**, the result is returned directly (no Promise)
2. If the task is **still pending**, a Promise is created and linked to the task via an internal ID
3. When the task completes on the C# side, the result is queued for delivery
4. On the **next frame tick**, the Promise is resolved (or rejected) and your `await` or `.then()` handler runs

This means async results arrive at least one frame after the task completes.

## Notes

- Only `Task` and `Task<T>` are supported (`ValueTask` is not supported)
- Pending tasks are resolved during the next `Tick()` call (up to 50 per frame to avoid stalling)
- If more than 100 tasks are pending, a warning is logged automatically
- For async asset loading from Unity's `Resources/` folder, see [`loadResourceAsync`](/docs/guides/assets#async-resource-loading)
- See [C# Interop](/docs/core-concepts/csharp-interop) for general C# usage from JavaScript

---

<!-- source: https://v3.onejs.com/docs/guides/zero-alloc -->
<!-- section: Guides -->

# Zero-Allocation Interop

The standard `CS` proxy uses reflection and allocates memory on every call. Fine for occasional use, but in per-frame loops this creates GC pressure and frame hitches. OneJS provides two systems to eliminate these allocations:

- **FastPath**: intercepts regular `CS` proxy calls and handles them with typed delegates. No JS changes needed.
- **`za` API**: explicit zero-alloc function bindings from JavaScript. For complex static method calls.

## FastPath

### Built-in Registrations

Common Unity types are pre-registered. These are already zero-alloc with no setup:

- **Time**: `deltaTime`, `unscaledDeltaTime`, `time`, `frameCount`, `timeScale`, etc.
- **Transform**: `position`, `localPosition`, `rotation`, `localScale`, `forward`, `eulerAngles`, etc.
- **GameObject**: `activeSelf`, `activeInHierarchy`, `name`, `tag`, `layer`, `transform`
- **Input**: `mousePosition`, `GetKey`, `GetAxis`, etc. (legacy input)
- **Screen**: `width`, `height`, `dpi`
- **Mathf**: `Sin`, `Cos`, `Abs`, `Sqrt`, `Floor`, `Ceil`, `Round`

### Registering Your Own Types

Register properties you read per-frame in C#:

```csharp
public class PlayerController : MonoBehaviour
{
    public int Health { get; set; } = 100;
    public int Gold { get; set; } = 50;
    public float Speed { get; set; } = 5f;

    void Awake()
    {
        // Register once. All instances of this type benefit.
        QuickJSNative.FastPath.Property<PlayerController, int>("Health", p => p.Health);
        QuickJSNative.FastPath.Property<PlayerController, int>("Gold", p => p.Gold);
        QuickJSNative.FastPath.Property<PlayerController, float>(
            "Speed", p => p.Speed, (p, v) => p.Speed = v  // getter + setter
        );
    }
}
```

JavaScript stays the same. `useFrameSync` and direct property access both benefit:

```tsx
// These are now zero-alloc on the C# side
const health = useFrameSync(() => player.Health)
const gold = useFrameSync(() => player.Gold)
```

Only register properties you actually read per-frame. Most apps only need a handful. The typed lambdas compile to direct method calls, making them AOT-safe on all platforms including iOS and consoles. A source generator approach could automate this in the future, but manual registration keeps things explicit and avoids adding build infrastructure.

### Registration API

```csharp
// Instance properties
FastPath.Property<TTarget, TValue>(name, getter)
FastPath.Property<TTarget, TValue>(name, getter, setter)

// Static properties
FastPath.StaticProperty<TOwner, TValue>(name, getter)
FastPath.StaticProperty<TOwner, TValue>(name, getter, setter)

// Instance methods (0-1 args, with or without return)
FastPath.Method<TTarget>(name, action)
FastPath.Method<TTarget, TResult>(name, func)
FastPath.Method<TTarget, TArg0, TResult>(name, func)
FastPath.Method<TTarget, TArg0>(name, action)

// Static methods (0-6 args)
FastPath.StaticMethod<TOwner, TResult>(name, func)
FastPath.StaticMethod<TOwner, TArg0, TResult>(name, func)
// ... up to 6 arguments
```

### Checking Registrations

```csharp
FastPath.IsTypeRegistered<PlayerController>()          // any registrations for this type?
FastPath.IsRegistered<PlayerController>("Health")      // specific member?
FastPath.GetRegisteredMembers<PlayerController>()      // ["Health", "Gold", "Speed"]
```

### Supported Types

Primitives and Unity structs are fully zero-alloc. Strings and reference types still allocate on the C# side.

| Type | Zero-alloc |
|------|-----------|
| `int`, `float`, `double`, `bool`, `long` | Yes |
| `Vector2`, `Vector3`, `Vector4`, `Quaternion`, `Color` | Yes |
| `string` | No (UTF8 marshaling) |
| Reference types | No (handle + type hint) |

## `za` API

For complex static method calls (GPU compute, physics batching, etc.) where you need explicit control over the binding.

```tsx
import { za } from "onejs-unity/interop"
```

### Pre-registered Bindings (zero-alloc)

Register typed delegates in C# and use them from JS by binding ID:

```csharp
// C#: register and expose binding IDs
public static int RaycastId = QuickJSNative.Bind<float, float, float, float, float, float, float, bool>(
    (ox, oy, oz, dx, dy, dz, dist) => Physics.Raycast(
        new Vector3(ox, oy, oz), new Vector3(dx, dy, dz), dist
    )
);
```

```tsx
// JS: use binding ID for zero-alloc calls
const raycast = za.fromId(MyBridge.RaycastId, 7)

function update() {
    if (raycast(ox, oy, oz, dx, dy, dz, maxDist)) {
        // hit
    }
    requestAnimationFrame(update)
}
```

### Dynamic Bindings (reduced alloc)

For convenience when pre-registration isn't worth the setup. Faster than `CS` proxy but still allocates per call:

```tsx
const Physics = za.static("UnityEngine.Physics", {
    Raycast: 4,
    SphereCast: 5,
})

Physics.Raycast(origin, direction, maxDistance, layerMask)
```

Single method variant:

```tsx
const getTime = za.method("UnityEngine.Time", "get_time", 0)
```

### Debugging

```tsx
console.log("Binding count:", za.getBindingCount())
const info = za.getBindingInfo(bindingId)
// { typeName, methodName, argCount }
```

## When to Use What

| Approach | GC Alloc | JS Changes | Best for |
|----------|----------|------------|----------|
| Standard `CS` proxy | High | None | Prototyping, occasional calls |
| FastPath | Zero | None | Per-frame property reads, `useFrameSync` |
| `za.static()` / `za.method()` | Reduced | Yes | Development, non-critical paths |
| `za.fromId()` | Zero | Yes | Maximum performance static methods |

Use FastPath for property reads and simple methods. Use `za.fromId()` for complex static method dispatch like [GPU compute](/docs/guides/gpu-compute). For most apps, FastPath alone is sufficient.

## Limitations

| Limitation | Workaround |
|------------|------------|
| `za` max 8 arguments | Split into multiple calls |
| `za` static methods only | Create static C# wrappers |
| No generic methods | Use concrete overloads |
| Strings valid during call only | Copy if needed beyond call |

---

<!-- source: https://v3.onejs.com/docs/guides/gpu-compute -->
<!-- section: Guides -->

# GPU Compute

OneJS provides a bridge to Unity's compute shader API, enabling GPU-accelerated computations from JavaScript. The `onejs-unity` package offers a fluent TypeScript API for working with compute shaders.

**Related:** [Zero-Allocation Interop](/docs/guides/zero-alloc) (for per-frame dispatch optimization)

## Platform Support

| Platform | Compute Shaders | Async Readback |
|----------|-----------------|----------------|
| Windows/macOS/Linux | Yes | Yes |
| iOS/Android | Yes (most devices) | Yes |
| WebGL | No | No |
| WebGPU | Yes | Yes |

## Setup

### 1. Register Shaders in C#

Compute shaders must be registered before JavaScript can access them:

```csharp
using OneJS.GPU;

public class MyShaderProvider : MonoBehaviour {
    public ComputeShader particleShader;

    void OnEnable() {
        GPUBridge.Register("ParticleUpdate", particleShader);
    }

    void OnDisable() {
        GPUBridge.Unregister("ParticleUpdate");
    }
}
```

### 2. Install onejs-unity

```bash
npm install onejs-unity
```

## Basic Usage

```typescript
import { compute, Platform } from "onejs-unity"

// Check platform support
if (!Platform.supportsCompute) {
    console.log("Compute shaders not supported")
    return
}

// Load a registered shader
const shader = await compute.load("ParticleUpdate")

// Create a buffer with initial data
const positions = compute.buffer({
    data: new Float32Array([0, 0, 0, 1, 1, 1])
})

// Dispatch a kernel with the fluent API
shader.kernel("CSMain")
    .float("deltaTime", 0.016)
    .float("speed", 5.0)
    .buffer("positions", positions)
    .dispatch(1)

// Read results back from GPU
const result = await positions.read()
console.log(result) // Float32Array with updated values

// Clean up
positions.dispose()
shader.dispose()
```

## Fluent API

The kernel builder provides a chainable API for setting uniforms and dispatching:

### Scalar Uniforms

```typescript
shader.kernel("CSMain")
    .float("time", performance.now() / 1000)
    .int("count", 1024)
    .bool("enabled", true)
```

### Vector Uniforms

```typescript
shader.kernel("CSMain")
    .vec2("resolution", [1920, 1080])
    .vec3("gravity", [0, -9.8, 0])
    .vec4("color", [1, 0.5, 0.2, 1])
```

Vectors accept arrays or objects with `x`, `y`, `z`, `w` properties.

### Matrix Uniforms

```typescript
const transform = new Float32Array(16)
// ... fill matrix data

shader.kernel("CSMain")
    .matrix("worldMatrix", transform)
```

### Buffer Bindings

```typescript
// Create buffers
const input = compute.buffer({ data: new Float32Array(1024) })
const output = compute.buffer({ count: 1024 })

// Bind to kernel
shader.kernel("CSMain")
    .buffer("inputData", input)
    .buffer("outputData", output)
    .dispatch(16)  // 16 thread groups
```

### Dispatch

```typescript
// 1D dispatch
shader.kernel("CSMain").dispatch(64)

// 2D dispatch
shader.kernel("CSMain").dispatch(32, 32)

// 3D dispatch
shader.kernel("CSMain").dispatch(8, 8, 8)

// Multiple iterations
shader.kernel("Simulate").repeat(100)
```

## Buffers

### Creating Buffers

```typescript
// From existing data
const buffer = compute.buffer({
    data: new Float32Array([1, 2, 3, 4])
})

// Empty buffer with count
const empty = compute.buffer({ count: 1024 })

// Typed buffers
const ints = compute.buffer({
    data: new Int32Array([1, 2, 3])
})
```

### Writing Data

```typescript
buffer.write(new Float32Array([5, 6, 7, 8]))
```

### Reading Data (Async)

GPU readback is asynchronous:

```typescript
const result = await buffer.read()
```

For non-blocking checks:

```typescript
// Start readback
buffer.read().then(data => {
    console.log("Readback complete:", data)
})

// Check if ready
if (buffer.readbackReady) {
    const data = buffer.readbackResult
}
```

### Structured Buffers

Define struct types matching your HLSL:

```typescript
// HLSL struct:
// struct Particle {
//     float3 position;
//     float3 velocity;
//     float life;
// };

const ParticleType = compute.struct({
    position: "float3",
    velocity: "float3",
    life: "float"
})

const particles = compute.buffer({
    count: 1000,
    type: ParticleType
})
```

## Compute Shader Example

HLSL compute shader (`ParticleUpdate.compute`):

```csharp
#pragma kernel CSMain

RWStructuredBuffer<float3> positions;
float deltaTime;
float speed;
uint count;

[numthreads(64, 1, 1)]
void CSMain(uint id : SV_DispatchThreadID) {
    if (id >= count) return;
    positions[id] += float3(0, speed * deltaTime, 0);
}
```

JavaScript usage:

```typescript
const shader = await compute.load("ParticleUpdate")
const positions = compute.buffer({
    data: new Float32Array([0,0,0, 1,0,0, 2,0,0]) // 3 particles
})

// Update loop
function update(dt: number) {
    shader.kernel("CSMain")
        .float("deltaTime", dt)
        .float("speed", 2.0)
        .int("count", 3)
        .buffer("positions", positions)
        .dispatch(1)
}
```

## VFX Graph Integration

Compute shaders can drive VFX Graph parameters by writing to shared buffers:

1. Create a compute shader that writes particle data
2. Use a GraphicsBuffer shared between compute and VFX Graph
3. Dispatch from JavaScript to update the buffer
4. VFX Graph reads the buffer each frame

This enables JavaScript-controlled particle systems with GPU performance.

## Performance Tips

- Minimize readbacks: GPU-to-CPU transfers are slow
- Batch dispatches when possible
- Use appropriate thread group sizes (typically 64, 128, or 256)
- Keep buffers GPU-resident when data doesn't need CPU access
- Profile with Unity's Frame Debugger
- Use [zero-allocation interop](/docs/guides/zero-alloc) for per-frame dispatch calls

## API Reference

### Platform

```typescript
Platform.supportsCompute      // boolean
Platform.supportsAsyncReadback // boolean
Platform.maxComputeWorkGroupSize // [x, y, z]
```

### compute

```typescript
compute.load(name: string): Promise<ComputeShader>
compute.buffer<T>(options: BufferOptions<T>): ComputeBuffer<T>
compute.struct(schema: StructSchema): StructType
```

### ComputeShader

```typescript
shader.kernel(name: string): KernelBuilder
shader.readback<T>(bufferName: string): Promise<T>
shader.dispose(): void
```

### KernelBuilder

```typescript
.float(name, value)    // Set float uniform
.int(name, value)      // Set int uniform
.bool(name, value)     // Set bool uniform
.vec2(name, value)     // Set Vector2
.vec3(name, value)     // Set Vector3
.vec4(name, value)     // Set Vector4
.matrix(name, value)   // Set Matrix4x4
.buffer(name, data)    // Bind buffer
.dispatch(x, y?, z?)   // Execute kernel
.repeat(iterations)    // Execute multiple times
```

### ComputeBuffer

```typescript
buffer.count           // Number of elements
buffer.stride          // Bytes per element
buffer.write(data)     // Upload data
buffer.read()          // Async readback
buffer.readbackReady   // Check if ready
buffer.readbackResult  // Get cached result
buffer.dispose()       // Release resources
```

---

<!-- source: https://v3.onejs.com/docs/guides/vector-drawing -->
<!-- section: Guides -->

# Vector Drawing

OneJS exposes Unity's `Painter2D` API for GPU-accelerated vector graphics. Any element can render custom vector content via the `onGenerateVisualContent` prop.

**Use cases**: Charts, graphs, custom shapes, progress indicators, path animations, game UI overlays.

## Basic Usage

```tsx
import { View, render } from "onejs-react"

function Circle() {
    return (
        <View
            style={{ width: 200, height: 200, backgroundColor: "#333" }}
            onGenerateVisualContent={(mgc) => {
                const p = mgc.painter2D

                // Set fill color (red)
                p.fillColor = new CS.UnityEngine.Color(1, 0, 0, 1)

                // Draw a circle
                p.BeginPath()
                p.Arc(
                    new CS.UnityEngine.Vector2(100, 100), // center
                    80,                                   // radius
                    CS.UnityEngine.UIElements.Angle.Degrees(0),
                    CS.UnityEngine.UIElements.Angle.Degrees(360),
                    CS.UnityEngine.UIElements.ArcDirection.Clockwise
                )
                p.Fill(CS.UnityEngine.UIElements.FillRule.NonZero)
            }}
        />
    )
}

render(<Circle />, __root)
```

## How It Works

The `onGenerateVisualContent` prop maps directly to Unity's `generateVisualContent` delegate on VisualElement:

1. React reconciler assigns your callback to the element's `generateVisualContent` property
2. Unity calls your callback during the repaint phase
3. Your callback receives a `MeshGenerationContext` with access to `painter2D`
4. Drawing commands are batched and rendered on the GPU

No C# code modifications are needed. The existing interop layer handles the delegate assignment.

## Path Operations

Painter2D uses a path-based drawing model similar to HTML5 Canvas:

```tsx
onGenerateVisualContent={(mgc) => {
    const p = mgc.painter2D

    // Start a new path
    p.BeginPath()

    // Move to starting point (no line drawn)
    p.MoveTo(new CS.UnityEngine.Vector2(10, 10))

    // Draw lines
    p.LineTo(new CS.UnityEngine.Vector2(100, 10))
    p.LineTo(new CS.UnityEngine.Vector2(100, 100))

    // Close path back to start
    p.ClosePath()

    // Render the path
    p.strokeColor = new CS.UnityEngine.Color(1, 1, 1, 1)
    p.lineWidth = 2
    p.Stroke()
}}
```

### Path Methods

| Method | Description |
|--------|-------------|
| `BeginPath()` | Start a new path, clearing any existing path data |
| `MoveTo(point)` | Move to point without drawing a line |
| `LineTo(point)` | Draw a line from current position to point |
| `ClosePath()` | Close the path by drawing a line back to the starting point |
| `Arc(center, radius, startAngle, endAngle, direction)` | Draw an arc or circle |
| `ArcTo(p1, p2, radius)` | Draw an arc tangent to two lines |
| `BezierCurveTo(cp1, cp2, end)` | Draw a cubic bezier curve |
| `QuadraticCurveTo(cp, end)` | Draw a quadratic bezier curve |

### Rendering Methods

| Method | Description |
|--------|-------------|
| `Fill(fillRule)` | Fill the current path using the specified fill rule |
| `Stroke()` | Stroke (outline) the current path |

Fill rules:
- `FillRule.NonZero` - Standard fill (most common)
- `FillRule.OddEven` - Alternate fill for complex shapes with holes

## Styling Properties

```tsx
onGenerateVisualContent={(mgc) => {
    const p = mgc.painter2D

    // Colors
    p.fillColor = new CS.UnityEngine.Color(0.2, 0.6, 1.0, 1.0)  // RGBA
    p.strokeColor = new CS.UnityEngine.Color(1, 1, 1, 0.8)

    // Line styling
    p.lineWidth = 3
    p.lineCap = CS.UnityEngine.UIElements.LineCap.Round
    p.lineJoin = CS.UnityEngine.UIElements.LineJoin.Round
    p.miterLimit = 10
}}
```

### Properties Reference

| Property | Type | Description |
|----------|------|-------------|
| `fillColor` | `Color` | Fill color for `Fill()` |
| `strokeColor` | `Color` | Stroke color for `Stroke()` |
| `lineWidth` | `float` | Stroke width in pixels |
| `lineCap` | `LineCap` | Line end style: Butt, Round, Square |
| `lineJoin` | `LineJoin` | Line corner style: Miter, Round, Bevel |
| `miterLimit` | `float` | Limit for miter joins before beveling |

## Triggering Repaints

The callback is only invoked when Unity decides the element needs repainting. To trigger a repaint when your drawing state changes, call `MarkDirtyRepaint()`:

```tsx
import { View, render } from "onejs-react"
import { useState, useEffect, useRef } from "react"

function AnimatedCircle() {
    const ref = useRef<CS.UnityEngine.UIElements.VisualElement>(null)
    const [radius, setRadius] = useState(50)

    // Animate radius
    useEffect(() => {
        const interval = setInterval(() => {
            setRadius(r => 30 + Math.sin(Date.now() / 500) * 20)
        }, 16)
        return () => clearInterval(interval)
    }, [])

    // Trigger repaint when radius changes
    useEffect(() => {
        ref.current?.MarkDirtyRepaint()
    }, [radius])

    return (
        <View
            ref={ref}
            style={{ width: 200, height: 200 }}
            onGenerateVisualContent={(mgc) => {
                const p = mgc.painter2D
                p.fillColor = new CS.UnityEngine.Color(0, 0.5, 1, 1)
                p.BeginPath()
                p.Arc(
                    new CS.UnityEngine.Vector2(100, 100),
                    radius,
                    CS.UnityEngine.UIElements.Angle.Degrees(0),
                    CS.UnityEngine.UIElements.Angle.Degrees(360),
                    CS.UnityEngine.UIElements.ArcDirection.Clockwise
                )
                p.Fill(CS.UnityEngine.UIElements.FillRule.NonZero)
            }}
        />
    )
}
```

### Cleaner Pattern: `useVectorContent`

`onejs-react` ships a `useVectorContent` hook that handles the ref, callback assignment, and `MarkDirtyRepaint()` automatically when dependencies change. The same animated circle, rewritten:

```tsx
import { View, render, useVectorContent } from "onejs-react"
import { useState, useEffect } from "react"
import { Color } from "UnityEngine"
import { Angle, ArcDirection, FillRule } from "UnityEngine/UIElements"

function AnimatedCircle() {
    const [radius, setRadius] = useState(50)

    useEffect(() => {
        const id = setInterval(() => {
            setRadius(30 + Math.sin(Date.now() / 500) * 20)
        }, 16)
        return () => clearInterval(id)
    }, [])

    const ref = useVectorContent((mgc) => {
        const p = mgc.painter2D
        p.fillColor = new Color(0, 0.5, 1, 1)
        p.BeginPath()
        p.Arc(
            new CS.UnityEngine.Vector2(100, 100),
            radius,
            Angle.Degrees(0),
            Angle.Degrees(360),
            ArcDirection.Clockwise
        )
        p.Fill(FillRule.NonZero)
    }, [radius])

    return <View ref={ref} style={{ width: 200, height: 200 }} />
}
```

The draw callback re-runs and the element repaints whenever any value in the deps array changes (same semantics as `useEffect`).

## Practical Examples

### Pie Chart

```tsx
function PieChart({ data }: { data: { value: number; color: Color }[] }) {
    const total = data.reduce((sum, d) => sum + d.value, 0)

    return (
        <View
            style={{ width: 200, height: 200 }}
            onGenerateVisualContent={(mgc) => {
                const p = mgc.painter2D
                const center = new CS.UnityEngine.Vector2(100, 100)
                const radius = 80
                const Angle = CS.UnityEngine.UIElements.Angle
                const Clockwise = CS.UnityEngine.UIElements.ArcDirection.Clockwise

                let startAngle = -90 // Start at top

                for (const slice of data) {
                    const sweepAngle = (slice.value / total) * 360
                    const endAngle = startAngle + sweepAngle

                    p.fillColor = slice.color
                    p.BeginPath()
                    p.MoveTo(center)
                    p.Arc(
                        center,
                        radius,
                        Angle.Degrees(startAngle),
                        Angle.Degrees(endAngle),
                        Clockwise
                    )
                    p.ClosePath()
                    p.Fill(CS.UnityEngine.UIElements.FillRule.NonZero)

                    startAngle = endAngle
                }
            }}
        />
    )
}
```

### Progress Ring

```tsx
function ProgressRing({ progress }: { progress: number }) {
    return (
        <View
            style={{ width: 120, height: 120 }}
            onGenerateVisualContent={(mgc) => {
                const p = mgc.painter2D
                const center = new CS.UnityEngine.Vector2(60, 60)
                const radius = 50
                const thickness = 8
                const Angle = CS.UnityEngine.UIElements.Angle
                const Clockwise = CS.UnityEngine.UIElements.ArcDirection.Clockwise

                // Background ring
                p.strokeColor = new CS.UnityEngine.Color(0.2, 0.2, 0.2, 1)
                p.lineWidth = thickness
                p.lineCap = CS.UnityEngine.UIElements.LineCap.Round
                p.BeginPath()
                p.Arc(center, radius, Angle.Degrees(0), Angle.Degrees(360), Clockwise)
                p.Stroke()

                // Progress arc
                p.strokeColor = new CS.UnityEngine.Color(0.2, 0.8, 0.4, 1)
                p.BeginPath()
                p.Arc(
                    center,
                    radius,
                    Angle.Degrees(-90),
                    Angle.Degrees(-90 + 360 * progress),
                    Clockwise
                )
                p.Stroke()
            }}
        />
    )
}
```

### Custom Shape

```tsx
function Star({ points = 5, outerRadius = 50, innerRadius = 25 }) {
    return (
        <View
            style={{ width: 120, height: 120 }}
            onGenerateVisualContent={(mgc) => {
                const p = mgc.painter2D
                const cx = 60, cy = 60

                p.fillColor = new CS.UnityEngine.Color(1, 0.8, 0, 1)
                p.BeginPath()

                for (let i = 0; i < points * 2; i++) {
                    const radius = i % 2 === 0 ? outerRadius : innerRadius
                    const angle = (Math.PI / points) * i - Math.PI / 2
                    const x = cx + Math.cos(angle) * radius
                    const y = cy + Math.sin(angle) * radius

                    if (i === 0) {
                        p.MoveTo(new CS.UnityEngine.Vector2(x, y))
                    } else {
                        p.LineTo(new CS.UnityEngine.Vector2(x, y))
                    }
                }

                p.ClosePath()
                p.Fill(CS.UnityEngine.UIElements.FillRule.NonZero)
            }}
        />
    )
}
```

## Comparison with HTML5 Canvas

If you're familiar with HTML5 Canvas, here are the key differences:

| Feature | Unity Painter2D | HTML5 Canvas |
|---------|-----------------|--------------|
| Transforms | Not built-in | translate(), rotate(), scale() |
| State Stack | Not built-in | save(), restore() |
| Gradients | Limited (strokeGradient) | createLinearGradient, createRadialGradient |
| Text | Via MeshGenerationContext | fillText(), strokeText() |
| Images | Via DrawVectorImage() | drawImage() |
| Shadows | Not available | shadowBlur, shadowColor |
| Clipping | Via nested VisualElements | clip() |

### Handling Transforms

Painter2D has no built-in transforms or state stack. `onejs-react` ships a `Transform2D` helper that provides client-side matrix math, so you can write code that feels like Canvas:

```tsx
import { Transform2D } from "onejs-react"
import { FillRule } from "UnityEngine/UIElements"

onGenerateVisualContent={(mgc) => {
    const p = mgc.painter2D
    const t = new Transform2D()

    // Center origin and rotate 45 degrees
    t.translate(100, 100)
    t.rotate(Math.PI / 4)

    // Draw a square in transformed space
    const corners = t.points([-40, -40], [40, -40], [40, 40], [-40, 40])
    p.BeginPath()
    p.MoveTo(corners[0])
    for (let i = 1; i < corners.length; i++) p.LineTo(corners[i])
    p.ClosePath()
    p.Fill(FillRule.NonZero)
}}
```

`Transform2D` API:

| Method | Purpose |
|--------|---------|
| `translate(x, y)` | Move origin |
| `rotate(rad)` | Rotate (radians, clockwise) |
| `scale(x, y?)` | Scale (uniform if `y` omitted) |
| `save()` / `restore()` | Push/pop the current matrix |
| `reset()` | Reset to identity |
| `point(x, y)` | Transform a single point to `Vector2` |
| `points(...[x, y][])` | Transform multiple points at once |
| `setTransform(a, b, c, d, e, f)` | Set the matrix directly |
| `transform(a, b, c, d, e, f)` | Multiply current matrix by another |

`save()` and `restore()` use an internal stack, so you can isolate transforms for nested shapes:

```tsx
const t = new Transform2D()
t.translate(150, 150)

t.save()
    t.rotate(angle)
    // draw outer shape using t.point()/t.points()
t.restore()

t.rotate(-angle * 2)
t.scale(0.5)
// draw inner shape with an independent transform
```

If you'd rather skip the helper and compute coordinates by hand:

```tsx
function rotatePoint(x: number, y: number, cx: number, cy: number, angle: number) {
    const cos = Math.cos(angle)
    const sin = Math.sin(angle)
    const dx = x - cx
    const dy = y - cy
    return new CS.UnityEngine.Vector2(
        cx + dx * cos - dy * sin,
        cy + dx * sin + dy * cos
    )
}
```

## Text Drawing

For text, use `MeshGenerationContext` directly instead of `painter2D`:

```tsx
onGenerateVisualContent={(mgc) => {
    // Vector drawing
    const p = mgc.painter2D
    p.fillColor = new CS.UnityEngine.Color(0.2, 0.2, 0.2, 1)
    // ... draw background

    // Text drawing (separate API)
    // Note: DrawText API depends on Unity version
    // Check Unity documentation for MeshGenerationContext.DrawText
}}
```

## Performance Tips

1. **Minimize path complexity**: Complex paths with many points are more expensive
2. **Batch similar draws**: Group elements with similar colors/styles
3. **Avoid frequent repaints**: Only call `MarkDirtyRepaint()` when necessary
4. **Use simple shapes when possible**: Arcs and lines are faster than complex bezier curves
5. **Consider caching**: For static graphics, render once and avoid state changes

## API Reference

### Types

```typescript
// Available via CS.UnityEngine namespace
type Vector2 = CS.UnityEngine.Vector2
type Color = CS.UnityEngine.Color

// Available via CS.UnityEngine.UIElements namespace
type Angle = CS.UnityEngine.UIElements.Angle
type ArcDirection = CS.UnityEngine.UIElements.ArcDirection
type LineCap = CS.UnityEngine.UIElements.LineCap
type LineJoin = CS.UnityEngine.UIElements.LineJoin
type FillRule = CS.UnityEngine.UIElements.FillRule
type Painter2D = CS.UnityEngine.UIElements.Painter2D
type MeshGenerationContext = CS.UnityEngine.UIElements.MeshGenerationContext
```

### Creating Values

```typescript
// Vector2
new CS.UnityEngine.Vector2(x, y)

// Color (RGBA, 0-1 range)
new CS.UnityEngine.Color(r, g, b, a)

// Angle
CS.UnityEngine.UIElements.Angle.Degrees(degrees)
CS.UnityEngine.UIElements.Angle.Radians(radians)

// Enums
CS.UnityEngine.UIElements.ArcDirection.Clockwise
CS.UnityEngine.UIElements.ArcDirection.CounterClockwise
CS.UnityEngine.UIElements.FillRule.NonZero
CS.UnityEngine.UIElements.FillRule.OddEven
CS.UnityEngine.UIElements.LineCap.Butt
CS.UnityEngine.UIElements.LineCap.Round
CS.UnityEngine.UIElements.LineCap.Square
CS.UnityEngine.UIElements.LineJoin.Miter
CS.UnityEngine.UIElements.LineJoin.Round
CS.UnityEngine.UIElements.LineJoin.Bevel
```

## Related

- [Unity Painter2D Documentation](https://docs.unity3d.com/6000.2/Documentation/ScriptReference/UIElements.Painter2D.html)
- [Unity Generate 2D Visual Content Guide](https://docs.unity3d.com/6000.2/Documentation/Manual/UIE-generate-2d-visual-content.html)

---

<!-- source: https://v3.onejs.com/docs/guides/custom-elements -->
<!-- section: Guides -->

# Custom Elements

Use `registerElement` and `createComponent` to turn any C# `VisualElement` subclass into a React component.

## Import

```tsx
import { registerElement, createComponent } from "onejs-react"
```

## Defining a Custom Element

Create a C# class that inherits from `VisualElement`:

```csharp
using UnityEngine.UIElements;

public class RadialProgress : VisualElement {
    public float progress { get; set; }
    public string trackColor { get; set; }
    public float lineWidth { get; set; } = 4f;
}
```

## Registration

Register the element once at the top of your entry file. The first argument is a name for the element. The second is the C# constructor via the `CS` proxy.

```tsx
registerElement("radial-progress", CS.RadialProgress)
```

For types inside a namespace:

```tsx
registerElement("health-bar", CS.MyGame.UI.HealthBar)
```

## Creating a Component

Use `createComponent` to get a typed React component:

```tsx
import type { BaseProps } from "onejs-react"

interface RadialProgressProps extends BaseProps {
    progress?: number
    trackColor?: string
    lineWidth?: number
}

const RadialProgress = createComponent<RadialProgressProps>("radial-progress")
```

Then use it like any built-in component:

```tsx
<RadialProgress
    progress={0.75}
    trackColor="#3498db"
    lineWidth={6}
    style={{ width: 100, height: 100 }}
    className="my-progress"
/>
```

## How Props Work

Standard React props are handled by the reconciler automatically. Everything else is forwarded directly to the C# element as property assignments.

| Prop Type | Handled By | Example |
|-----------|------------|---------|
| `style` | Reconciler | `style={{ width: 100 }}` |
| `className` | Reconciler | `className="my-class"` |
| Events | Reconciler | `onClick={handler}` |
| `ref` | Reconciler | `ref={myRef}` |
| Custom props | C# element | `progress={0.75}` |

## Events

Event handlers work the same as built-in components:

```tsx
<RadialProgress
    progress={0.5}
    onClick={(e) => console.log("Clicked at", e.x, e.y)}
    onPointerEnter={() => console.log("Hover")}
/>
```

See [Events](/docs/core-concepts/events) for the full list of supported event props.

## Refs

Refs point to the underlying C# element:

```tsx
import { useRef, useEffect } from "react"

function MyComponent() {
    const ref = useRef(null)

    useEffect(() => {
        if (ref.current) {
            console.log(ref.current.GetType().Name) // "RadialProgress"
            ref.current.MarkDirtyRepaint()
        }
    }, [])

    return <RadialProgress ref={ref} progress={0.5} />
}
```

See [Refs](/docs/core-concepts/refs) for more on working with element references.

## Complete Example

Putting it all together:

```tsx
import { registerElement, createComponent, render, View, Label } from "onejs-react"
import type { BaseProps } from "onejs-react"
import { useState } from "react"

// Define props
interface HealthBarProps extends BaseProps {
    current?: number
    max?: number
    barColor?: string
}

// Register and create component
registerElement("health-bar", CS.MyGame.UI.HealthBar)
const HealthBar = createComponent<HealthBarProps>("health-bar")

// Use in your app
function PlayerHUD() {
    const [hp, setHp] = useState(80)

    return (
        <View style={{ padding: 16 }}>
            <Label text={`HP: ${hp}/100`} />
            <HealthBar
                current={hp}
                max={100}
                barColor="#e74c3c"
                style={{ width: 200, height: 20 }}
            />
        </View>
    )
}

render(<PlayerHUD />, __root)
```

---

<!-- source: https://v3.onejs.com/docs/guides/type-generation -->
<!-- section: Guides -->

# Type Generation

OneJS provides TypeScript declarations for C# types so you get IntelliSense, autocomplete, and type checking in your editor.

## Unity Types (`unity-types`)

The `unity-types` npm package provides pre-generated declarations for standard Unity assemblies: CoreModule, UIElements, Physics, Audio, InputSystem, and more.

Install it as a dev dependency:

```bash
npm install -D unity-types
```

Once installed, your editor will provide IntelliSense for `CS.UnityEngine.*` types and ES6-style imports from Unity namespaces.

## Project Types (JSRunner)

For types from your own C# code (e.g., `Assembly-CSharp`), JSRunner has built-in auto-generation.

In the JSRunner inspector, open the **Typings** section. Toggle **Auto Generate Typings** on and configure which assemblies to include (e.g., `Assembly-CSharp`, `Assembly-CSharp-Editor`).

Generated declarations are written to `{WorkingDir}/typings/index.d.ts`. They regenerate automatically on domain reload, which happens at editor startup and after any C# recompile. You can also trigger regeneration manually from the inspector.

## Custom Packages (Type Generator Window)

For third-party packages or specific assemblies, use the Type Generator window at **Tools > OneJS > Type Generator**.

The window has three panels: an assembly selector on the left, a type browser in the middle, and a live preview on the right. You can filter assemblies by category (Unity, User, etc.) and search for specific types.

Select the types you need and click **Generate** to save a `.d.ts` file.

### Programmatic API

You can also generate declarations from C# scripts:

```csharp
TypeGenerator.Create()
    .AddAssemblyByName("MyCustomPackage")
    .IncludeDocumentation()
    .Build()
    .WriteTo("types/my-package.d.ts");
```

This is useful for CI pipelines or editor tooling that needs to keep type declarations in sync automatically.

---

<!-- source: https://v3.onejs.com/docs/guides/cartridges -->
<!-- section: Guides -->

# UI Cartridges

Cartridges package reusable source files and Unity assets into a single ScriptableObject. Drop one onto a JSRunner and its files become importable modules, its objects become accessible from JavaScript.

## Quick Example

A `theme` cartridge bundles a stylesheet and some Unity assets:

```
Cartridge: "theme"
  Files:    variables.uss
  Objects:  logo -> LogoTexture, font -> InterFont
```

In your app:

```tsx
import "@cartridges/theme/variables.uss"

function Header() {
    const { logo, font } = __cart("theme")

    return (
        <View className="header">
            <Image src={logo} />
            <Label text="My App" style={{ unityFontDefinition: font }} />
        </View>
    )
}
```

## Setup

1. **Create** -- Right-click in the Project window, **Create > OneJS > UI Cartridge**
2. **Configure** -- Set a **slug** (e.g., `theme`), add files and/or objects in the inspector
3. **Add to JSRunner** -- Drag the asset into the **Cartridges** tab
4. **Extract** -- Click **Extract** to write files to disk (also happens automatically on first run and during builds)

Files are extracted to `@cartridges/{slug}/` inside your working directory, along with a `.d.ts` file for autocomplete.

## Accessing Files

Cartridge files are regular source files that esbuild can import:

```typescript
import { ColorWheel } from "@cartridges/color-picker/index"
import "@cartridges/theme/variables.uss"
```

## Accessing Objects

Object entries are available at runtime as properties on the cartridge:

```typescript
const palette = __cart("color-picker").palette    // Texture2D
const config = __cart("color-picker").config      // ScriptableObject
```

Each cartridge auto-generates a `.d.ts` file, so you get full autocomplete and type checking for object keys.

## Namespaces

Optional namespaces organize cartridges like npm scoped packages. Set the **Namespace** field in the inspector:

```typescript
__cart("color-picker")              // no namespace
__cart("@acme/color-picker")        // with namespace "acme"
```

Namespaced cartridges extract to `@cartridges/@{namespace}/{slug}/`.

## Builds

The build processor extracts cartridge files automatically during Unity builds. Cartridge objects are injected into the JavaScript context at startup -- `__cart()` is available immediately when your app runs.

---

<!-- source: https://v3.onejs.com/docs/components/view -->
<!-- section: Components -->

# View

`View` is the basic layout container. It maps to UI Toolkit's `VisualElement`.

## Import

```tsx
import { View } from "onejs-react"
```

## Basic Usage

```tsx
<View style={{ padding: 20, backgroundColor: "#1a1a1a" }}>
    <Label text="Content inside a View" />
</View>
```

## Props

| Prop | Type | Description |
|------|------|-------------|
| `style` | `ViewStyle` | Inline styles |
| `className` | `string` | USS class name(s) |
| `children` | `ReactNode` | Child elements |
| `onClick` | `(e) => void` | Click handler |
| `onPointerDown` | `(e) => void` | Pointer down handler |
| `onPointerUp` | `(e) => void` | Pointer up handler |
| `onPointerMove` | `(e) => void` | Pointer move handler |
| `onPointerEnter` | `(e) => void` | Pointer enter handler |
| `onPointerLeave` | `(e) => void` | Pointer leave handler |

## Flexbox Layout

View uses flexbox by default. Column direction is the default:

```tsx
// Vertical stack (default)
<View>
    <Label text="First" style={{ marginBottom: 10 }} />
    <Label text="Second" style={{ marginBottom: 10 }} />
    <Label text="Third" />
</View>

// Horizontal row
<View style={{ flexDirection: "row" }}>
    <Button text="One" style={{ marginRight: 10 }} />
    <Button text="Two" style={{ marginRight: 10 }} />
    <Button text="Three" />
</View>
```

> **Note**: USS doesn't support the `gap` property. Use margins on child elements instead.

## Common Layouts

### Centered Content

```tsx
<View style={{
    height: "100%",
    justifyContent: "center",
    alignItems: "center",
}}>
    <Label text="Centered" />
</View>
```

### Space Between

```tsx
<View style={{
    flexDirection: "row",
    justifyContent: "space-between",
    padding: 20,
}}>
    <Label text="Left" />
    <Label text="Right" />
</View>
```

### Flexible Children

```tsx
<View style={{ flexDirection: "row", height: 100 }}>
    <View style={{ flexGrow: 1, backgroundColor: "#333" }} />
    <View style={{ flexGrow: 2, backgroundColor: "#555" }} />
    <View style={{ flexGrow: 1, backgroundColor: "#777" }} />
</View>
```

### Absolute Positioning

```tsx
<View style={{ position: "relative", height: 200 }}>
    <View style={{
        position: "absolute",
        top: 10,
        right: 10,
        width: 50,
        height: 50,
        backgroundColor: "red",
    }} />
</View>
```

## Interactive View

```tsx
function ClickableCard() {
    const [active, setActive] = useState(false)

    return (
        <View
            style={{
                padding: 20,
                backgroundColor: active ? "#0066cc" : "#333",
                borderRadius: 8,
            }}
            onClick={() => setActive(!active)}
        >
            <Label text={active ? "Active" : "Click me"} />
        </View>
    )
}
```

---

<!-- source: https://v3.onejs.com/docs/components/label -->
<!-- section: Components -->

# Label

`Label` displays text. Maps to UI Toolkit's `Label`.

## Import

```tsx
import { Label } from "onejs-react"
```

## Basic Usage

```tsx
<Label text="Hello, World!" />
```

## Props

| Prop | Type | Description |
|------|------|-------------|
| `text` | `string` | Text content |
| `style` | `ViewStyle` | Inline styles |
| `className` | `string` | USS class name(s) |

## Text Styling

```tsx
// Heading
<Label
    text="Page Title"
    style={{
        fontSize: 32,
        fontStyle: "bold",
        color: "#ffffff",
        marginBottom: 20,
    }}
/>

// Paragraph
<Label
    text="This is body text with normal styling."
    style={{
        fontSize: 16,
        color: "#999999",
        marginBottom: 10,
    }}
/>

// Caption
<Label
    text="Small caption text"
    style={{
        fontSize: 12,
        color: "#666666",
    }}
/>
```

## Text Alignment

```tsx
<Label
    text="Centered text"
    style={{
        unityTextAlign: "middle-center",
        width: "100%",
    }}
/>

// Alignment options:
// "upper-left", "upper-center", "upper-right"
// "middle-left", "middle-center", "middle-right"
// "lower-left", "lower-center", "lower-right"
```

## Dynamic Text

```tsx
function Score({ value }) {
    return <Label text={`Score: ${value}`} style={{ fontSize: 24 }} />
}

function Timer({ seconds }) {
    const mins = Math.floor(seconds / 60)
    const secs = seconds % 60
    return (
        <Label
            text={`${mins}:${secs.toString().padStart(2, '0')}`}
            style={{ fontSize: 48, fontStyle: "bold" }}
        />
    )
}
```

## Rich Text

UI Toolkit supports basic rich text tags:

```tsx
<Label text="<b>Bold</b> and <i>italic</i> text" />
<Label text="<color=#ff0000>Red text</color>" />
<Label text="<size=24>Large</size> and <size=12>small</size>" />
```

## Text Wrapping

```tsx
<Label
    text="This is a long text that will wrap to multiple lines when it exceeds the container width."
    style={{
        width: 200,
        whiteSpace: "normal",  // Enable wrapping
    }}
/>
```

---

<!-- source: https://v3.onejs.com/docs/components/text -->
<!-- section: Components -->

# Text

`Text` displays inline text content. Maps to UI Toolkit's `TextElement`.

## Import

```tsx
import { Text } from "onejs-react"
```

## Basic Usage

```tsx
<Text text="Hello, World!" />
```

Or with children (raw text):

```tsx
<View>
    Hello, World!
</View>
```

Raw text inside JSX elements automatically creates `TextElement` instances.

## Props

| Prop | Type | Description |
|------|------|-------------|
| `text` | `string` | Text content (alternative to children) |
| `style` | `ViewStyle` | Inline styles |
| `className` | `string` | USS class name(s) |
| `children` | `ReactNode` | Child content |

## Text vs Label

Both display text, but they have different purposes:

| Component | Use Case |
|-----------|----------|
| `<Text>` | Primary text display, inline content |
| `<Label>` | Form labels, semantic labeling |

```tsx
// Use Text for content
<Text text="Welcome to our app" style={{ fontSize: 24 }} />

// Use Label for form fields
<View>
    <Label text="Username" />
    <TextField placeholder="Enter username" />
</View>
```

## Styling

```tsx
<Text
    text="Styled text"
    style={{
        fontSize: 18,
        color: "#ffffff",
        fontStyle: "bold",
        unityTextAlign: "middle-center",
    }}
/>
```

## Text Alignment

```tsx
<View style={{ width: 200 }}>
    <Text text="Left aligned" style={{ unityTextAlign: "upper-left" }} />
    <Text text="Centered" style={{ unityTextAlign: "upper-center" }} />
    <Text text="Right aligned" style={{ unityTextAlign: "upper-right" }} />
</View>
```

Available alignment values:
- `upper-left`, `upper-center`, `upper-right`
- `middle-left`, `middle-center`, `middle-right`
- `lower-left`, `lower-center`, `lower-right`

## Wrapping

```tsx
// Allow wrapping (default)
<Text
    text="This is a long text that will wrap to multiple lines"
    style={{ whiteSpace: "normal", width: 200 }}
/>

// Prevent wrapping
<Text
    text="This text stays on one line"
    style={{ whiteSpace: "nowrap" }}
/>
```

## Dynamic Content

```tsx
function Counter() {
    const [count, setCount] = useState(0)

    return (
        <View>
            <Text text={`Count: ${count}`} style={{ fontSize: 20 }} />
            <Button text="Increment" onClick={() => setCount(c => c + 1)} />
        </View>
    )
}
```

## Inline with Other Elements

```tsx
<View style={{ flexDirection: "row", alignItems: "center" }}>
    <Text text="Status: " />
    <Text text="Online" style={{ color: "#00ff00" }} />
</View>
```

---

<!-- source: https://v3.onejs.com/docs/components/button -->
<!-- section: Components -->

# Button

`Button` is a clickable element. Maps to UI Toolkit's `Button`.

## Import

```tsx
import { Button } from "onejs-react"
```

## Basic Usage

```tsx
<Button text="Click me" onClick={() => console.log("Clicked!")} />
```

## Props

| Prop | Type | Description |
|------|------|-------------|
| `text` | `string` | Button label |
| `style` | `ViewStyle` | Inline styles |
| `className` | `string` | USS class name(s) |
| `onClick` | `(e) => void` | Click handler |

## Styled Buttons

```tsx
// Primary button
<Button
    text="Submit"
    style={{
        backgroundColor: "#0066cc",
        color: "#ffffff",
        paddingTop: 10,
        paddingBottom: 10,
        paddingLeft: 20,
        paddingRight: 20,
        borderRadius: 4,
        borderWidth: 0,
    }}
    onClick={handleSubmit}
/>

// Outline button
<Button
    text="Cancel"
    style={{
        backgroundColor: "transparent",
        borderWidth: 1,
        borderColor: "#666",
        color: "#666",
        paddingTop: 10,
        paddingBottom: 10,
        paddingLeft: 20,
        paddingRight: 20,
        borderRadius: 4,
    }}
    onClick={handleCancel}
/>
```

## Button States

Handle disabled and loading states:

```tsx
function SubmitButton({ loading, disabled, onSubmit }) {
    return (
        <Button
            text={loading ? "Loading..." : "Submit"}
            style={{
                backgroundColor: disabled ? "#666" : "#0066cc",
                opacity: disabled ? 0.5 : 1,
            }}
            onClick={disabled ? undefined : onSubmit}
        />
    )
}
```

## Button Row

```tsx
<View style={{ flexDirection: "row" }}>
    <Button text="Save" onClick={handleSave} style={{ marginRight: 10 }} />
    <Button text="Cancel" onClick={handleCancel} />
</View>
```

## With USS

```css
/* buttons.uss */
.btn {
    padding: 10px 20px;
    border-radius: 4px;
    border-width: 0;
}

.btn-primary {
    background-color: #0066cc;
    color: #ffffff;
}

.btn-primary:hover {
    background-color: #0055aa;
}
```

```tsx
<Button text="Styled" className="btn btn-primary" onClick={handleClick} />
```

---

<!-- source: https://v3.onejs.com/docs/components/textfield -->
<!-- section: Components -->

# TextField

`TextField` is a text input. Maps to UI Toolkit's `TextField`.

## Import

```tsx
import { TextField } from "onejs-react"
```

## Basic Usage

```tsx
function NameInput() {
    const [name, setName] = useState("")

    return (
        <TextField
            value={name}
            onChange={(e) => setName(e.value)}
            placeholder="Enter your name"
        />
    )
}
```

## Props

| Prop | Type | Description |
|------|------|-------------|
| `value` | `string` | Current text value |
| `placeholder` | `string` | Placeholder text |
| `multiline` | `boolean` | Enable multiline input |
| `readOnly` | `boolean` | Make field read-only |
| `maxLength` | `number` | Maximum character count |
| `style` | `ViewStyle` | Inline styles |
| `className` | `string` | USS class name(s) |
| `onChange` | `(e) => void` | Value change handler |
| `onFocus` | `(e) => void` | Focus handler |
| `onBlur` | `(e) => void` | Blur handler |

## Controlled Input

```tsx
function SearchBox() {
    const [query, setQuery] = useState("")

    const handleSearch = () => {
        console.log("Searching for:", query)
    }

    return (
        <View style={{ flexDirection: "row" }}>
            <TextField
                value={query}
                onChange={(e) => setQuery(e.value)}
                placeholder="Search..."
                style={{ flexGrow: 1, marginRight: 10 }}
            />
            <Button text="Search" onClick={handleSearch} />
        </View>
    )
}
```

## Multiline

```tsx
<TextField
    value={description}
    onChange={(e) => setDescription(e.value)}
    placeholder="Enter description..."
    multiline={true}
    style={{ height: 100 }}
/>
```

## Validation

```tsx
function EmailInput() {
    const [email, setEmail] = useState("")
    const [error, setError] = useState("")

    const validate = (value) => {
        if (!value.includes("@")) {
            setError("Please enter a valid email")
        } else {
            setError("")
        }
    }

    return (
        <View>
            <TextField
                value={email}
                onChange={(e) => {
                    setEmail(e.value)
                    validate(e.value)
                }}
                placeholder="Email address"
                style={{
                    borderColor: error ? "#ff0000" : "#333",
                }}
            />
            {error && <Label text={error} style={{ color: "#ff0000", fontSize: 12 }} />}
        </View>
    )
}
```

## Password Field

```tsx
function PasswordInput() {
    const [password, setPassword] = useState("")

    return (
        <TextField
            value={password}
            onChange={(e) => setPassword(e.value)}
            placeholder="Password"
            // Note: UI Toolkit doesn't have a built-in password mask
            // You'd need to implement this with a custom element or USS
        />
    )
}
```

## Styled Input

```tsx
<TextField
    value={text}
    onChange={(e) => setText(e.value)}
    style={{
        backgroundColor: "#2a2a2a",
        borderWidth: 1,
        borderColor: "#444",
        borderRadius: 4,
        paddingTop: 10,
        paddingBottom: 10,
        paddingLeft: 12,
        paddingRight: 12,
        fontSize: 16,
        color: "#ffffff",
    }}
/>
```

---

<!-- source: https://v3.onejs.com/docs/components/toggle -->
<!-- section: Components -->

# Toggle

`Toggle` is a boolean switch. Maps to UI Toolkit's `Toggle`.

## Import

```tsx
import { Toggle } from "onejs-react"
```

## Basic Usage

```tsx
function Settings() {
    const [enabled, setEnabled] = useState(false)

    return (
        <Toggle
            value={enabled}
            onChange={(e) => setEnabled(e.value)}
            label="Enable notifications"
        />
    )
}
```

## Props

| Prop | Type | Description |
|------|------|-------------|
| `value` | `boolean` | Current state |
| `label` | `string` | Label text |
| `style` | `ViewStyle` | Inline styles |
| `className` | `string` | USS class name(s) |
| `onChange` | `(e) => void` | Change handler |

## Settings List

```tsx
function SettingsPanel() {
    const [settings, setSettings] = useState({
        sound: true,
        music: true,
        vibration: false,
        notifications: true,
    })

    const toggle = (key) => {
        setSettings(s => ({ ...s, [key]: !s[key] }))
    }

    return (
        <View>
            <Toggle
                value={settings.sound}
                onChange={() => toggle("sound")}
                label="Sound Effects"
                style={{ marginBottom: 15 }}
            />
            <Toggle
                value={settings.music}
                onChange={() => toggle("music")}
                label="Background Music"
                style={{ marginBottom: 15 }}
            />
            <Toggle
                value={settings.vibration}
                onChange={() => toggle("vibration")}
                label="Vibration"
                style={{ marginBottom: 15 }}
            />
            <Toggle
                value={settings.notifications}
                onChange={() => toggle("notifications")}
                label="Push Notifications"
            />
        </View>
    )
}
```

## Styled Toggle

```tsx
<Toggle
    value={active}
    onChange={(e) => setActive(e.value)}
    label="Dark Mode"
    style={{
        marginBottom: 10,
    }}
/>
```

## Without Label

```tsx
<View style={{ flexDirection: "row", alignItems: "center" }}>
    <Label text="Enable feature" style={{ marginRight: 10 }} />
    <Toggle
        value={enabled}
        onChange={(e) => setEnabled(e.value)}
    />
</View>
```

---

<!-- source: https://v3.onejs.com/docs/components/slider -->
<!-- section: Components -->

# Slider

`Slider` is a range input. Maps to UI Toolkit's `Slider`.

## Import

```tsx
import { Slider } from "onejs-react"
```

## Basic Usage

```tsx
function VolumeControl() {
    const [volume, setVolume] = useState(50)

    return (
        <Slider
            value={volume}
            lowValue={0}
            highValue={100}
            onChange={(e) => setVolume(e.value)}
        />
    )
}
```

## Props

| Prop | Type | Description |
|------|------|-------------|
| `value` | `number` | Current value |
| `lowValue` | `number` | Minimum value |
| `highValue` | `number` | Maximum value |
| `style` | `ViewStyle` | Inline styles |
| `className` | `string` | USS class name(s) |
| `onChange` | `(e) => void` | Change handler |

## With Label

```tsx
function VolumeSlider() {
    const [volume, setVolume] = useState(75)

    return (
        <View>
            <View style={{ flexDirection: "row", justifyContent: "space-between", marginBottom: 10 }}>
                <Label text="Volume" />
                <Label text={`${Math.round(volume)}%`} />
            </View>
            <Slider
                value={volume}
                lowValue={0}
                highValue={100}
                onChange={(e) => setVolume(e.value)}
            />
        </View>
    )
}
```

## Multiple Sliders

```tsx
function AudioSettings() {
    const [master, setMaster] = useState(100)
    const [music, setMusic] = useState(80)
    const [sfx, setSfx] = useState(90)

    return (
        <View>
            <View style={{ marginBottom: 20 }}>
                <Label text={`Master: ${master}%`} style={{ marginBottom: 5 }} />
                <Slider value={master} lowValue={0} highValue={100} onChange={(e) => setMaster(e.value)} />
            </View>
            <View style={{ marginBottom: 20 }}>
                <Label text={`Music: ${music}%`} style={{ marginBottom: 5 }} />
                <Slider value={music} lowValue={0} highValue={100} onChange={(e) => setMusic(e.value)} />
            </View>
            <View>
                <Label text={`Sound Effects: ${sfx}%`} style={{ marginBottom: 5 }} />
                <Slider value={sfx} lowValue={0} highValue={100} onChange={(e) => setSfx(e.value)} />
            </View>
        </View>
    )
}
```

## Custom Range

```tsx
// Temperature: -20 to 40 degrees
<Slider
    value={temperature}
    lowValue={-20}
    highValue={40}
    onChange={(e) => setTemperature(e.value)}
/>

// Float values: 0.0 to 1.0
<Slider
    value={opacity}
    lowValue={0}
    highValue={1}
    onChange={(e) => setOpacity(e.value)}
/>
```

## Styled Slider

```tsx
<Slider
    value={value}
    lowValue={0}
    highValue={100}
    onChange={(e) => setValue(e.value)}
    style={{
        width: 200,
        marginTop: 10,
        marginBottom: 10,
    }}
/>
```

---

<!-- source: https://v3.onejs.com/docs/components/scrollview -->
<!-- section: Components -->

# ScrollView

`ScrollView` is a scrollable container. Maps to UI Toolkit's `ScrollView`.

## Import

```tsx
import { ScrollView } from "onejs-react"
```

## Basic Usage

```tsx
<ScrollView style={{ height: 300 }}>
    {items.map((item, i) => (
        <View key={i} style={{ padding: 10, borderBottomWidth: 1, borderColor: "#333" }}>
            <Label text={item.name} />
        </View>
    ))}
</ScrollView>
```

## Props

### Basic Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `mode` | `"Vertical"`, `"Horizontal"`, `"VerticalAndHorizontal"` | `"Vertical"` | Scroll direction |
| `horizontalScrollerVisibility` | `"Auto"`, `"AlwaysVisible"`, `"Hidden"` | `"Auto"` | Horizontal scrollbar visibility |
| `verticalScrollerVisibility` | `"Auto"`, `"AlwaysVisible"`, `"Hidden"` | `"Auto"` | Vertical scrollbar visibility |
| `style` | `ViewStyle` | | Inline styles |
| `className` | `string` | | USS class name(s) |
| `children` | `ReactNode` | | Scrollable content |

### Scroll Behavior

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `elasticity` | `number` | `0.1` | Elasticity for elastic touch scrolling |
| `elasticAnimationIntervalMs` | `number` | `10` | Interval for elastic animation in milliseconds |
| `scrollDecelerationRate` | `number` | `0.135` | Deceleration rate after touch release |
| `mouseWheelScrollSize` | `number` | `18` | Scroll distance per mouse wheel tick |
| `horizontalPageSize` | `number` | | Page size for horizontal pagination |
| `verticalPageSize` | `number` | | Page size for vertical pagination |

### Touch Behavior

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `touchScrollBehavior` | `"Unrestricted"`, `"Elastic"`, `"Clamped"` | `"Clamped"` | How touch scrolling behaves at boundaries |

### Nested Scrolling

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `nestedInteractionKind` | `"Default"`, `"StopScrolling"`, `"ForwardScrolling"` | `"Default"` | How nested ScrollViews interact |

## Scroll Modes

```tsx
// Vertical scrolling (default)
<ScrollView mode="Vertical" style={{ height: 400 }}>
    {content}
</ScrollView>

// Horizontal scrolling
<ScrollView mode="Horizontal" style={{ width: 400 }}>
    <View style={{ flexDirection: "row" }}>
        {items.map(item => <Card key={item.id} data={item} />)}
    </View>
</ScrollView>

// Both directions
<ScrollView mode="VerticalAndHorizontal" style={{ width: 400, height: 400 }}>
    {largeContent}
</ScrollView>
```

## Scrollbar Visibility

```tsx
// Always show scrollbar
<ScrollView verticalScrollerVisibility="AlwaysVisible">
    {content}
</ScrollView>

// Hide scrollbar
<ScrollView verticalScrollerVisibility="Hidden">
    {content}
</ScrollView>

// Auto (show when needed)
<ScrollView verticalScrollerVisibility="Auto">
    {content}
</ScrollView>
```

## Chat Log Example

```tsx
function ChatLog({ messages }) {
    return (
        <ScrollView style={{ height: 400, backgroundColor: "#1a1a1a" }}>
            <View style={{ padding: 10 }}>
                {messages.map((msg, i) => (
                    <View key={i} style={{
                        padding: 10,
                        marginBottom: 10,
                        backgroundColor: msg.isMe ? "#0066cc" : "#333",
                        borderRadius: 8,
                        alignSelf: msg.isMe ? "flex-end" : "flex-start",
                        maxWidth: "80%",
                    }}>
                        <Label text={msg.text} style={{ color: "#fff" }} />
                    </View>
                ))}
            </View>
        </ScrollView>
    )
}
```

## List Example

```tsx
function ItemList({ items, onSelect }) {
    return (
        <ScrollView style={{ height: 300 }}>
            {items.map((item) => (
                <View
                    key={item.id}
                    style={{
                        padding: 15,
                        borderBottomWidth: 1,
                        borderColor: "#333",
                    }}
                    onClick={() => onSelect(item)}
                >
                    <Label text={item.title} style={{ fontStyle: "bold" }} />
                    <Label text={item.description} style={{ color: "#999", fontSize: 14 }} />
                </View>
            ))}
        </ScrollView>
    )
}
```

## Horizontal Gallery

```tsx
function ImageGallery({ images }) {
    return (
        <ScrollView mode="Horizontal" style={{ height: 150 }}>
            <View style={{ flexDirection: "row" }}>
                {images.map((url, i) => (
                    <View key={i} style={{
                        width: 120,
                        height: 120,
                        marginRight: 10,
                        backgroundColor: "#333",
                        borderRadius: 8,
                    }}>
                        {/* Image component would go here */}
                    </View>
                ))}
            </View>
        </ScrollView>
    )
}
```

---

<!-- source: https://v3.onejs.com/docs/components/image -->
<!-- section: Components -->

# Image

Displays images and textures. Maps to UI Toolkit's `Image` element.

```tsx
import { Image } from "onejs-react"
```

## Basic Usage

Use the `src` prop with a path relative to your project's `assets/` folder:

```tsx
<Image src="logo.png" style={{ width: 100, height: 100 }} />
```

SVG files are also supported. They're parsed at runtime and rendered as resolution-independent vector graphics:

```tsx
<Image src="icons/star.svg" style={{ width: 64, height: 64 }} />
```

See the [Asset Loading](/docs/guides/assets) guide for details on how paths are resolved.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | | Path relative to `assets/` folder (PNG, JPG, SVG) |
| `image` | `Texture2D`, `VectorImage` | | Pre-loaded image object |
| `sprite` | `Sprite` | | Sprite to display |
| `scaleMode` | `"StretchToFill"`, `"ScaleAndCrop"`, `"ScaleToFit"` | `"ScaleToFit"` | How the image scales |
| `tintColor` | `string` | | Tint color applied to the image |
| `style` | `ViewStyle` | | Inline styles |
| `className` | `string` | | USS class name(s) |

When both `src` and `image` are provided, `src` takes precedence. The `image` prop auto-detects whether you're passing a `Texture2D` or `VectorImage` and sets the appropriate property on the underlying UI Toolkit element.

## SVG Support

SVG files placed in your `assets/` folder work with both `src` and `loadImage()`:

```tsx
import { loadImage } from "onejs-unity/assets"

// Via src prop (simplest)
<Image src="icons/heart.svg" style={{ width: 32, height: 32 }} />

// Via loadImage (when you need the object directly)
const heartIcon = loadImage("icons/heart.svg")
<Image image={heartIcon} style={{ width: 32, height: 32 }} />
```

Since SVGs are loaded as `VectorImage` objects, they scale cleanly at any size with no blurring or pixelation:

```tsx
<View style={{ flexDirection: "row", alignItems: "flex-end" }}>
    <Image src="icon.svg" style={{ width: 16, height: 16 }} />
    <Image src="icon.svg" style={{ width: 48, height: 48 }} />
    <Image src="icon.svg" style={{ width: 128, height: 128 }} />
</View>
```

Under the hood, SVG files are parsed at runtime using Unity's built-in `VectorGraphics` module and rendered as GPU-accelerated vector images.

## Scale Modes

```tsx
// Maintain aspect ratio, show entire image
<Image src="photo.png" scaleMode="ScaleToFit" />

// Maintain aspect ratio, fill container (crops edges)
<Image src="photo.png" scaleMode="ScaleAndCrop" />

// Ignore aspect ratio, fill container
<Image src="photo.png" scaleMode="StretchToFill" />
```

## Pre-loaded Images

For images loaded from custom paths or computed sources, use the `image` prop:

```tsx
import { loadImage } from "onejs-unity/assets"

const avatar = loadImage(`avatars/${userId}.png`)
<Image image={avatar} style={{ width: 64, height: 64, borderRadius: 32 }} />
```

## Background Images

Any element can use an image as its background via the `style` prop:

```tsx
import { loadImage } from "onejs-unity/assets"

const bg = loadImage("card-bg.png")

<View style={{ backgroundImage: bg, width: 300, height: 200, padding: 20 }}>
    <Label text="Card Content" style={{ color: "#fff" }} />
</View>
```

## Cache Management

The `Image` component caches loaded images for the lifetime of the JS context. To force a reload (e.g., after replacing files on disk):

```tsx
import { clearImageCache } from "onejs-react"

clearImageCache()
```

## GPU Compute Textures

RenderTextures from GPU compute can be displayed as background images:

```tsx
import { compute } from "onejs-unity"

function ComputeVisualization() {
    const [rt, setRt] = useState(null)

    useEffect(() => {
        const renderTex = compute.renderTexture({ width: 256, height: 256 })
        setRt(renderTex)
        return () => renderTex.dispose()
    }, [])

    return (
        <View style={{ backgroundImage: rt, width: 256, height: 256 }} />
    )
}
```

---

<!-- source: https://v3.onejs.com/docs/components/listview -->
<!-- section: Components -->

# ListView

`ListView` renders large lists efficiently using virtualization. Only visible items are rendered. Maps to UI Toolkit's `ListView`.

## Import

```tsx
import { ListView } from "onejs-react"
```

## Basic Usage

```tsx
const items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]

function FruitList() {
    return (
        <ListView
            itemsSource={items}
            fixedItemHeight={40}
            makeItem={() => new CS.UnityEngine.UIElements.Label()}
            bindItem={(element, index) => {
                element.text = items[index]
            }}
            style={{ height: 300 }}
        />
    )
}
```

## Props

### Required Props

| Prop | Type | Description |
|------|------|-------------|
| `itemsSource` | `unknown[]` | Array of items to display |
| `makeItem` | `() => VisualElement` | Factory function to create elements |
| `bindItem` | `(element, index) => void` | Function to populate element with data |

### Optional Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `unbindItem` | `(element, index) => void` | | Called when element is recycled |
| `destroyItem` | `(element) => void` | | Called when element is destroyed |
| `fixedItemHeight` | `number` | | Fixed height for all items |
| `virtualizationMethod` | `"FixedHeight"`, `"DynamicHeight"` | `"FixedHeight"` | Virtualization strategy |

### Selection Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `selectionType` | `"None"`, `"Single"`, `"Multiple"` | `"Single"` | Selection mode |
| `selectedIndex` | `number` | | Currently selected index |
| `selectedIndices` | `number[]` | | Selected indices (multiple) |
| `onSelectionChange` | `(indices: number[]) => void` | | Selection change callback |
| `onItemsChosen` | `(items: unknown[]) => void` | | Double-click/Enter callback |

### Reordering Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `reorderable` | `boolean` | `false` | Enable drag reordering |
| `reorderMode` | `"Simple"`, `"Animated"` | `"Simple"` | Reorder animation style |

### Appearance Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `showBorder` | `boolean` | `false` | Show border around list |
| `showAlternatingRowBackgrounds` | `"None"`, `"ContentOnly"`, `"All"` | `"None"` | Zebra striping |
| `showFoldoutHeader` | `boolean` | `false` | Collapsible header |
| `headerTitle` | `string` | | Header text |
| `showAddRemoveFooter` | `boolean` | `false` | Add/remove buttons |

## Why Imperative API?

ListView uses callbacks instead of React children because it handles virtualization internally. Unity's ListView recycles elements as you scroll, so:

1. `makeItem` creates visual elements only when needed
2. `bindItem` updates recycled elements with new data
3. This is much more efficient than React diffing for large lists

## Selection Example

```tsx
function SelectableList({ items, onSelect }) {
    const [selectedIndex, setSelectedIndex] = useState(-1)

    return (
        <ListView
            itemsSource={items}
            fixedItemHeight={50}
            selectionType="Single"
            selectedIndex={selectedIndex}
            onSelectionChange={(indices) => {
                setSelectedIndex(indices[0] ?? -1)
                onSelect(items[indices[0]])
            }}
            makeItem={() => {
                const label = new CS.UnityEngine.UIElements.Label()
                label.style.paddingLeft = 10
                label.style.paddingTop = 15
                return label
            }}
            bindItem={(element, index) => {
                element.text = items[index].name
            }}
            style={{ height: 400 }}
        />
    )
}
```

## Complex Items

```tsx
function ContactList({ contacts }) {
    return (
        <ListView
            itemsSource={contacts}
            fixedItemHeight={60}
            makeItem={() => {
                const container = new CS.UnityEngine.UIElements.VisualElement()
                container.style.flexDirection = CS.UnityEngine.UIElements.FlexDirection.Row
                container.style.alignItems = CS.UnityEngine.UIElements.Align.Center
                container.style.paddingLeft = 10
                container.style.paddingRight = 10

                const avatar = new CS.UnityEngine.UIElements.VisualElement()
                avatar.name = "avatar"
                avatar.style.width = 40
                avatar.style.height = 40
                avatar.style.borderRadius = 20
                avatar.style.backgroundColor = new CS.UnityEngine.Color(0.3, 0.3, 0.3, 1)
                container.Add(avatar)

                const info = new CS.UnityEngine.UIElements.VisualElement()
                info.style.marginLeft = 10

                const name = new CS.UnityEngine.UIElements.Label()
                name.name = "name"
                name.style.fontSize = 16
                info.Add(name)

                const email = new CS.UnityEngine.UIElements.Label()
                email.name = "email"
                email.style.fontSize = 12
                email.style.color = new CS.UnityEngine.Color(0.6, 0.6, 0.6, 1)
                info.Add(email)

                container.Add(info)
                return container
            }}
            bindItem={(element, index) => {
                const contact = contacts[index]
                element.Q("name").text = contact.name
                element.Q("email").text = contact.email
            }}
            style={{ height: 500 }}
        />
    )
}
```

## Alternating Rows

```tsx
<ListView
    itemsSource={items}
    fixedItemHeight={40}
    showAlternatingRowBackgrounds="ContentOnly"
    makeItem={() => new CS.UnityEngine.UIElements.Label()}
    bindItem={(element, index) => {
        element.text = items[index]
    }}
/>
```

## Multiple Selection

```tsx
function MultiSelectList({ items }) {
    const [selected, setSelected] = useState([])

    return (
        <View>
            <Label text={`Selected: ${selected.length} items`} />
            <ListView
                itemsSource={items}
                fixedItemHeight={40}
                selectionType="Multiple"
                selectedIndices={selected}
                onSelectionChange={setSelected}
                makeItem={() => new CS.UnityEngine.UIElements.Label()}
                bindItem={(element, index) => {
                    element.text = items[index]
                }}
                style={{ height: 300 }}
            />
        </View>
    )
}
```

## Performance Tips

1. **Use fixedItemHeight** when possible - it's faster than dynamic height
2. **Keep makeItem simple** - complex element creation slows initialization
3. **Cache element queries** - use `element.Q()` sparingly in bindItem
4. **Minimize allocations** - reuse objects in bindItem

```tsx
// Good: Simple, fast
makeItem={() => new CS.UnityEngine.UIElements.Label()}

// Avoid: Complex hierarchy in makeItem
makeItem={() => {
    // Building complex trees here is slow
    // Consider USS classes instead
}}
```

---

<!-- source: https://v3.onejs.com/docs/components/frosted-glass -->
<!-- section: Components -->

# FrostedGlass

A container that blurs the 3D scene behind it, creating a frosted glass effect. The blur pipeline is fully automatic. No camera or render texture setup needed.

<video src="/assets/videos/frosted-glass-demo.mp4" autoplay loop muted playsinline style="width:100%;max-width:640px;border-radius:12px;margin:1em 0"></video>

## Import

```tsx
import { FrostedGlass } from "onejs-react"
```

## Basic Usage

```tsx
<FrostedGlass style={{ width: 300, height: 200, borderRadius: 16 }}>
    <Label text="Hello from behind the glass" />
</FrostedGlass>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `blur` | `number` | `10` | Blur radius in screen pixels. Higher = more blurry |
| `tint` | `string` | `"rgba(255,255,255,0.15)"` | Tint color overlaid on the blurred background |
| `style` | `ViewStyle` | | Inline styles |
| `className` | `string` | | USS class name(s) |

## Tint Color

The `tint` prop accepts a CSS color string. Use alpha to control how much the tint blends with the blurred background:

```tsx
// Subtle white frost
<FrostedGlass tint="rgba(255,255,255,0.15)" />

// Colored glass
<FrostedGlass tint="rgba(25,200,240,0.2)" />

// Heavy tint
<FrostedGlass tint="rgba(0,0,0,0.5)" />
```

## Dynamic Blur

The blur radius can be adjusted at runtime:

```tsx
function BlurPanel() {
    const [blur, setBlur] = useState(10)

    return (
        <View>
            <FrostedGlass blur={blur}
                style={{ width: 300, height: 200, borderRadius: 16 }}>
                <Label text={`Blur: ${Math.round(blur)}`} />
            </FrostedGlass>
            <Slider
                value={blur}
                lowValue={0}
                highValue={40}
                onChange={(e) => setBlur(e.value)}
                style={{ width: 300, marginTop: 16 }}
            />
        </View>
    )
}
```

## How It Works

FrostedGlass captures the 3D scene using a lightweight clone camera (excluding UI), downsamples it, and applies a two-pass Gaussian blur. The blurred result is UV-mapped to the element's screen position so it always reflects what's directly behind it.

Multiple FrostedGlass elements share a single blur pass for efficiency.

## Rotation Example

The blur stays screen-aligned even when the element is rotated:

```tsx
function App() {
    const [blur, setBlur] = useState(10)
    const [rotation, setRotation] = useState(0)
    const rafRef = useRef<number>(0)

    useEffect(() => {
        const animate = () => {
            setRotation(r => (r + 0.5) % 360)
            rafRef.current = requestAnimationFrame(animate)
        }
        rafRef.current = requestAnimationFrame(animate)
        return () => cancelAnimationFrame(rafRef.current)
    }, [])

    return (
        <View style={{ justifyContent: "center", alignItems: "center",
            width: "100%", height: "100%" }}>
            <FrostedGlass blur={blur} tint="rgba(25, 243, 243, 0.15)"
                style={{ justifyContent: "center", alignItems: "center",
                    width: 300, height: 200, borderRadius: 16, rotate: rotation }}>
                <Label>Blur: {Math.round(blur)}</Label>
            </FrostedGlass>
            <Slider lowValue={0} highValue={40} value={blur}
                onChange={(e) => setBlur(e.value)}
                style={{ width: 300, marginTop: 16 }} />
        </View>
    )
}
```