@codexo/exojs-react 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codexo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @codexo/exojs-react
+
+React 18 / 19 bindings for [ExoJS](https://exojs.dev) — mount an ExoJS
+`Application` into your React tree, drive scenes declaratively, and overlay React
+HUD on the canvas.
+
+## Installation
+
+```sh
+npm install @codexo/exojs @codexo/exojs-react react
+```
+
+`@codexo/exojs` and `react` (>= 18) are peer dependencies; `react-dom` is an
+optional peer. The package ships pre-built ESM (`dist/esm`) with type
+declarations and works on both `@types/react` 18 and 19.
+
+## Two layers, pick what you need
+
+This package is intentionally layered:
+
+- **`useExoApplication` — headless.** Creates and owns the `Application`, binds
+  it to a `<canvas>` you render yourself. No DOM, no wrapper, no styling
+  opinions — full control.
+- **`<ExoCanvas>` — batteries-included.** Renders a positioned wrapper `<div>` +
+  a React-managed `<canvas>` and provides the app via context, so HUD overlays
+  work out of the box.
+
+## Quick start — `<ExoCanvas>`
+
+```tsx
+import { ExoCanvas, Scenes, Scene, useExoApp } from '@codexo/exojs-react';
+import { TitleScene, GameScene } from './scenes';
+
+function Game() {
+  return (
+    <ExoCanvas
+      options={{ canvas: { width: 1280, height: 720 }, clearColor: someColor }}
+      style={{ width: 1280, height: 720 }}
+    >
+      <Scenes active="game" transition={{ type: 'fade', duration: 0.3 }}>
+        <Scene name="title" component={TitleScene} />
+        <Scene name="game" component={GameScene}>
+          <Hud /> {/* absolutely-positioned React overlay, over the canvas */}
+        </Scene>
+      </Scenes>
+    </ExoCanvas>
+  );
+}
+
+function Hud() {
+  const app = useExoApp();
+  return <div style={{ position: 'absolute', top: 8, left: 8 }}>FPS overlay…</div>;
+}
+```
+
+Layout props (`style`, `className`, …) apply to the **wrapper**; size it to
+drive `'fill'`/`'letterbox'` sizing. Style the canvas itself via `canvasProps`.
+
+## Quick start — headless hook (full control)
+
+```tsx
+import { useExoApplication } from '@codexo/exojs-react';
+
+function Game() {
+  const { app, canvasRef } = useExoApplication({ canvas: { width: 800, height: 600 } });
+  // Render the canvas however and wherever you want.
+  return <canvas ref={canvasRef} className="my-canvas" />;
+}
+```
+
+## API
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `ExoCanvas` | component | Batteries-included canvas host (wrapper div + canvas + context). |
+| `useExoApplication(options?, onReady?)` | hook | Headless: owns the `Application`, returns `{ app, canvasRef }`. |
+| `useExoApp()` | hook | The `Application` from the nearest `<ExoCanvas>`/provider. Throws if absent. |
+| `useExoContext()` | hook | Like `useExoApp` but returns `Application \| null` (no throw). |
+| `ExoContext` | context | The underlying context (advanced / testing). |
+| `useScene(SceneClass, deps?)` | hook | Instantiate + activate a single scene; returns it once live. |
+| `Scenes` / `Scene` | components | Declarative scene switch over the one-active-scene model. |
+| `useActiveScene()` | hook | The active scene instance from the nearest `<Scenes>`. |
+
+### Reactivity model
+
+The `Application` is recreated only when an **identity** option changes — the
+render `backend` (WebGL2 ↔ WebGPU cannot be hot-swapped). Other supported options
+are applied **live**:
+
+- `canvas.width` / `canvas.height` → `app.resize(...)`
+- `canvas.sizingMode` → `app.sizingMode`
+- `clearColor` → `app.clearColor`
+
+Options without a live setter (`canvas.pixelRatio`, `seed`, `extensions`, …) are
+captured at creation; change the `backend` or remount to apply them.
+
+## License
+
+MIT © Codexo

package/dist/esm/ExoCanvas.d.ts

@@ -0,0 +1,43 @@
+import type { Application } from '@codexo/exojs';
+import { type CanvasHTMLAttributes, type HTMLAttributes, type ReactElement } from 'react';
+import { type ExoApplicationOptions } from './useExoApplication';
+export interface ExoCanvasProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Options forwarded to the ExoJS {@link Application}. Pass
+     * `canvas.width`/`height`/`sizingMode`/etc.; most options are captured at
+     * creation, but `canvas.width`/`height`, `canvas.sizingMode` and `clearColor`
+     * are applied live (see {@link useExoApplication}).
+     */
+    options?: ExoApplicationOptions;
+    /**
+     * Called once each time the {@link Application} is (re)created. The backend
+     * (WebGL2 / WebGPU) is not yet initialized at this point — that happens when
+     * the first {@link import('./useScene').useScene} child calls `app.start()`.
+     */
+    onReady?: (app: Application) => void;
+    /**
+     * Props forwarded to the inner `<canvas>` (e.g. its own `style`/`className`).
+     * `ref`, `width` and `height` are managed by the engine and cannot be set.
+     */
+    canvasProps?: Omit<CanvasHTMLAttributes<HTMLCanvasElement>, 'ref' | 'width' | 'height'>;
+}
+/**
+ * Batteries-included canvas host. Renders a **positioned wrapper `<div>`**
+ * containing a React-managed `<canvas>` bound to an ExoJS {@link Application},
+ * and provides the app to descendant hooks via context. Because the wrapper is
+ * `position: relative`, absolutely-positioned `children` (HUD overlays,
+ * {@link import('./Scenes').Scenes}) sit over the canvas out of the box.
+ *
+ * Layout props (`style`, `className`, …) apply to the **wrapper**; size it to
+ * size the canvas in `'fill'`/`'letterbox'` modes. Use {@link canvasProps} to
+ * style the canvas itself. For full control with no wrapper element, use the
+ * headless {@link useExoApplication} hook directly.
+ *
+ * @example
+ * ```tsx
+ * <ExoCanvas options={{ canvas: { width: 800, height: 600 } }} style={{ width: 800, height: 600 }}>
+ *   <Hud /> // absolutely-positioned overlay; works because the wrapper is relative
+ * </ExoCanvas>
+ * ```
+ */
+export declare function ExoCanvas({ options, onReady, canvasProps, children, style, ...divProps }: ExoCanvasProps): ReactElement;

package/dist/esm/ExoCanvas.js

@@ -0,0 +1,36 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import 'react';
+import { ExoContext } from './ExoContext.js';
+import { useExoApplication } from './useExoApplication.js';
+
+/** Default canvas style: block layout avoids the inline-element baseline gap. */
+const defaultCanvasStyle = { display: 'block' };
+/**
+ * Batteries-included canvas host. Renders a **positioned wrapper `<div>`**
+ * containing a React-managed `<canvas>` bound to an ExoJS {@link Application},
+ * and provides the app to descendant hooks via context. Because the wrapper is
+ * `position: relative`, absolutely-positioned `children` (HUD overlays,
+ * {@link import('./Scenes').Scenes}) sit over the canvas out of the box.
+ *
+ * Layout props (`style`, `className`, …) apply to the **wrapper**; size it to
+ * size the canvas in `'fill'`/`'letterbox'` modes. Use {@link canvasProps} to
+ * style the canvas itself. For full control with no wrapper element, use the
+ * headless {@link useExoApplication} hook directly.
+ *
+ * @example
+ * ```tsx
+ * <ExoCanvas options={{ canvas: { width: 800, height: 600 } }} style={{ width: 800, height: 600 }}>
+ *   <Hud /> // absolutely-positioned overlay; works because the wrapper is relative
+ * </ExoCanvas>
+ * ```
+ */
+function ExoCanvas({ options, onReady, canvasProps, children, style, ...divProps }) {
+    const { app, canvasRef } = useExoApplication(options, onReady);
+    const { style: canvasStyle, ...restCanvasProps } = canvasProps ?? {};
+    const wrapperStyle = { position: 'relative', ...style };
+    const mergedCanvasStyle = { ...defaultCanvasStyle, ...canvasStyle };
+    return (jsx(ExoContext.Provider, { value: app, children: jsxs("div", { style: wrapperStyle, ...divProps, children: [jsx("canvas", { ref: canvasRef, style: mergedCanvasStyle, ...restCanvasProps }), app !== null && children] }) }));
+}
+
+export { ExoCanvas };
+//# sourceMappingURL=ExoCanvas.js.map

package/dist/esm/ExoCanvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExoCanvas.js","sources":["../../../src/ExoCanvas.tsx"],"sourcesContent":[null],"names":["_jsx","_jsxs"],"mappings":";;;;;AAMA;AACA,MAAM,kBAAkB,GAAkB,EAAE,OAAO,EAAE,OAAO,EAAE;AAuB9D;;;;;;;;;;;;;;;;;;AAkBG;SACa,SAAS,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAkB,EAAA;AACvG,IAAA,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC;AAE9D,IAAA,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,eAAe,EAAE,GAAG,WAAW,IAAI,EAAE;IACpE,MAAM,YAAY,GAAkB,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,KAAK,EAAE;IACtE,MAAM,iBAAiB,GAAkB,EAAE,GAAG,kBAAkB,EAAE,GAAG,WAAW,EAAE;AAElF,IAAA,QACEA,GAAA,CAAC,UAAU,CAAC,QAAQ,IAAC,KAAK,EAAE,GAAG,EAAA,QAAA,EAC7BC,cAAK,KAAK,EAAE,YAAY,EAAA,GAAM,QAAQ,EAAA,QAAA,EAAA,CACpCD,GAAA,CAAA,QAAA,EAAA,EAAQ,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,KAAM,eAAe,EAAA,CAAI,EACxE,GAAG,KAAK,IAAI,IAAI,QAAQ,CAAA,EAAA,CACrB,EAAA,CACc;AAE1B;;;;"}

package/dist/esm/ExoContext.d.ts

@@ -0,0 +1,15 @@
+import type { Application } from '@codexo/exojs';
+/**
+ * Internal React context that carries the active {@link Application} instance
+ * created by {@link ExoCanvas}. Consumers should use the {@link useExoApp}
+ * hook rather than reading this context directly; the context object is
+ * exported for advanced use (e.g. testing, custom providers).
+ */
+export declare const ExoContext: import("react").Context<Application | null>;
+/**
+ * Returns the nearest {@link Application} from the React tree, or `null`
+ * when called outside of an {@link ExoCanvas}. Prefer {@link useExoApp} for
+ * component-level use — it throws an actionable error instead of returning
+ * null.
+ */
+export declare function useExoContext(): Application | null;

package/dist/esm/ExoContext.js

@@ -0,0 +1,23 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Internal React context that carries the active {@link Application} instance
+ * created by {@link ExoCanvas}. Consumers should use the {@link useExoApp}
+ * hook rather than reading this context directly; the context object is
+ * exported for advanced use (e.g. testing, custom providers).
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const ExoContext = createContext(null);
+ExoContext.displayName = 'ExoContext';
+/**
+ * Returns the nearest {@link Application} from the React tree, or `null`
+ * when called outside of an {@link ExoCanvas}. Prefer {@link useExoApp} for
+ * component-level use — it throws an actionable error instead of returning
+ * null.
+ */
+function useExoContext() {
+    return useContext(ExoContext);
+}
+
+export { ExoContext, useExoContext };
+//# sourceMappingURL=ExoContext.js.map

package/dist/esm/ExoContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExoContext.js","sources":["../../../src/ExoContext.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;AAKG;AACH;MACa,UAAU,GAAG,aAAa,CAAqB,IAAI;AAChE,UAAU,CAAC,WAAW,GAAG,YAAY;AAErC;;;;;AAKG;SACa,aAAa,GAAA;AAC3B,IAAA,OAAO,UAAU,CAAC,UAAU,CAAC;AAC/B;;;;"}

package/dist/esm/Scenes.d.ts

@@ -0,0 +1,53 @@
+import { type Scene as ExoScene, type SceneTransition } from '@codexo/exojs';
+import { type ReactElement, type ReactNode } from 'react';
+/**
+ * Returns the currently-active scene instance from the nearest {@link Scenes},
+ * or `null` while none is live. Useful for HUD/overlay components that need to
+ * read scene state.
+ */
+export declare function useActiveScene<T extends ExoScene = ExoScene>(): T | null;
+/** Props for a {@link Scene} declaration. */
+export interface SceneProps {
+    /** Unique name used to select this scene via {@link ScenesProps.active}. */
+    readonly name: string;
+    /** Scene class to instantiate when this scene becomes active. */
+    readonly component: new () => ExoScene;
+    /** React overlay (HUD) rendered only while this scene is active. */
+    readonly children?: ReactNode;
+}
+/**
+ * Declares one scene inside a {@link Scenes} switch. Renders nothing on its own —
+ * {@link Scenes} reads its props and renders its {@link SceneProps.children} only
+ * while the scene is active.
+ */
+export declare function Scene(_props: SceneProps): ReactElement | null;
+/** Props for the {@link Scenes} switch. */
+export interface ScenesProps {
+    /** Name of the active {@link Scene}. Changing it switches scenes. */
+    readonly active: string;
+    /** Optional transition (e.g. a fade) applied when switching scenes. */
+    readonly transition?: SceneTransition;
+    /** {@link Scene} declarations. */
+    readonly children?: ReactNode;
+}
+/**
+ * Declarative scene switch over the one-active-scene model. Renders a set of
+ * {@link Scene} declarations and activates the one whose `name` equals `active`
+ * via `app.start()` (first activation) or `app.scene.setScene()` (subsequent
+ * switches, with the optional `transition`). The active scene's React children
+ * (HUD overlay) render alongside, and can read the instance via
+ * {@link useActiveScene}.
+ *
+ * @example
+ * ```tsx
+ * <ExoCanvas>
+ *   <Scenes active={screen} transition={{ type: 'fade', duration: 0.3 }}>
+ *     <Scene name="title" component={TitleScene} />
+ *     <Scene name="game" component={GameScene}>
+ *       <Hud />
+ *     </Scene>
+ *   </Scenes>
+ * </ExoCanvas>
+ * ```
+ */
+export declare function Scenes({ active, transition, children }: ScenesProps): ReactElement;

package/dist/esm/Scenes.js

@@ -0,0 +1,95 @@
+import { jsx } from 'react/jsx-runtime';
+import { ApplicationStatus } from '@codexo/exojs';
+import { createContext, useState, useMemo, Children, isValidElement, useEffect, useContext } from 'react';
+import { useExoApp } from './useExoApp.js';
+
+/** Carries the active {@link ExoScene} instance to descendants (HUD overlays). */
+const ActiveSceneContext = createContext(null);
+ActiveSceneContext.displayName = 'ExoActiveScene';
+/**
+ * Returns the currently-active scene instance from the nearest {@link Scenes},
+ * or `null` while none is live. Useful for HUD/overlay components that need to
+ * read scene state.
+ */
+function useActiveScene() {
+    return useContext(ActiveSceneContext);
+}
+/**
+ * Declares one scene inside a {@link Scenes} switch. Renders nothing on its own —
+ * {@link Scenes} reads its props and renders its {@link SceneProps.children} only
+ * while the scene is active.
+ */
+function Scene(_props) {
+    return null;
+}
+/**
+ * Declarative scene switch over the one-active-scene model. Renders a set of
+ * {@link Scene} declarations and activates the one whose `name` equals `active`
+ * via `app.start()` (first activation) or `app.scene.setScene()` (subsequent
+ * switches, with the optional `transition`). The active scene's React children
+ * (HUD overlay) render alongside, and can read the instance via
+ * {@link useActiveScene}.
+ *
+ * @example
+ * ```tsx
+ * <ExoCanvas>
+ *   <Scenes active={screen} transition={{ type: 'fade', duration: 0.3 }}>
+ *     <Scene name="title" component={TitleScene} />
+ *     <Scene name="game" component={GameScene}>
+ *       <Hud />
+ *     </Scene>
+ *   </Scenes>
+ * </ExoCanvas>
+ * ```
+ */
+function Scenes({ active, transition, children }) {
+    const app = useExoApp();
+    const [instance, setInstance] = useState(null);
+    // Collect the <Scene> declarations from children (keyed by name).
+    const registry = useMemo(() => {
+        const map = new Map();
+        Children.forEach(children, child => {
+            if (isValidElement(child) && child.type === Scene) {
+                const props = child.props;
+                map.set(props.name, props);
+            }
+        });
+        return map;
+    }, [children]);
+    const entry = registry.get(active);
+    const SceneClass = entry?.component ?? null;
+    useEffect(() => {
+        if (SceneClass === null) {
+            setInstance(null);
+            void app.scene.setScene(null);
+            return;
+        }
+        let cancelled = false;
+        const scene = new SceneClass();
+        const apply = async () => {
+            if (app.status === ApplicationStatus.Stopped) {
+                // First activation initializes the backend and starts the frame loop;
+                // transitions only apply to subsequent switches.
+                await app.start(scene);
+            }
+            else {
+                await app.scene.setScene(scene, transition !== undefined ? { transition } : {});
+            }
+            if (!cancelled) {
+                setInstance(scene);
+            }
+        };
+        void apply();
+        return () => {
+            cancelled = true;
+            setInstance(null);
+        };
+        // Re-activate when the active name changes. SceneClass/transition derive
+        // from `active`; keying on app + active avoids re-instantiating each render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [app, active]);
+    return (jsx(ActiveSceneContext.Provider, { value: instance, children: instance !== null && entry?.children }));
+}
+
+export { Scene, Scenes, useActiveScene };
+//# sourceMappingURL=Scenes.js.map

package/dist/esm/Scenes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scenes.js","sources":["../../../src/Scenes.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;;AAeA;AACA,MAAM,kBAAkB,GAAG,aAAa,CAAkB,IAAI,CAAC;AAC/D,kBAAkB,CAAC,WAAW,GAAG,gBAAgB;AAEjD;;;;AAIG;SACa,cAAc,GAAA;AAC5B,IAAA,OAAO,UAAU,CAAC,kBAAkB,CAAa;AACnD;AAYA;;;;AAIG;AACG,SAAU,KAAK,CAAC,MAAkB,EAAA;AACtC,IAAA,OAAO,IAAI;AACb;AAYA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,SAAU,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAe,EAAA;AAClE,IAAA,MAAM,GAAG,GAAG,SAAS,EAAE;IACvB,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAkB,IAAI,CAAC;;AAG/D,IAAA,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAK;AAC5B,QAAA,MAAM,GAAG,GAAG,IAAI,GAAG,EAAsB;AACzC,QAAA,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,IAAG;YACjC,IAAI,cAAc,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE;AACjD,gBAAA,MAAM,KAAK,GAAG,KAAK,CAAC,KAAmB;gBACvC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC;YAC5B;AACF,QAAA,CAAC,CAAC;AACF,QAAA,OAAO,GAAG;AACZ,IAAA,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAEd,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;AAClC,IAAA,MAAM,UAAU,GAAG,KAAK,EAAE,SAAS,IAAI,IAAI;IAE3C,SAAS,CAAC,MAAK;AACb,QAAA,IAAI,UAAU,KAAK,IAAI,EAAE;YACvB,WAAW,CAAC,IAAI,CAAC;YACjB,KAAK,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YAC7B;QACF;QAEA,IAAI,SAAS,GAAG,KAAK;AACrB,QAAA,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE;AAE9B,QAAA,MAAM,KAAK,GAAG,YAA0B;YACtC,IAAI,GAAG,CAAC,MAAM,KAAK,iBAAiB,CAAC,OAAO,EAAE;;;AAG5C,gBAAA,MAAM,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;YACxB;iBAAO;gBACL,MAAM,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,KAAK,SAAS,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;YACjF;YACA,IAAI,CAAC,SAAS,EAAE;gBACd,WAAW,CAAC,KAAK,CAAC;YACpB;AACF,QAAA,CAAC;QAED,KAAK,KAAK,EAAE;AAEZ,QAAA,OAAO,MAAK;YACV,SAAS,GAAG,IAAI;YAChB,WAAW,CAAC,IAAI,CAAC;AACnB,QAAA,CAAC;;;;AAIH,IAAA,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAEjB,IAAA,QACEA,GAAA,CAAC,kBAAkB,CAAC,QAAQ,EAAA,EAAC,KAAK,EAAE,QAAQ,YACzC,QAAQ,KAAK,IAAI,IAAI,KAAK,EAAE,QAAQ,EAAA,CACT;AAElC;;;;"}

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+export type { ExoCanvasProps } from './ExoCanvas';
+export { ExoCanvas } from './ExoCanvas';
+export { ExoContext, useExoContext } from './ExoContext';
+export type { SceneProps, ScenesProps } from './Scenes';
+export { Scene, Scenes, useActiveScene } from './Scenes';
+export { useExoApp } from './useExoApp';
+export type { ExoApplicationOptions, UseExoApplicationResult } from './useExoApplication';
+export { useExoApplication } from './useExoApplication';
+export { useScene } from './useScene';

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+export { ExoCanvas } from './ExoCanvas.js';
+export { ExoContext, useExoContext } from './ExoContext.js';
+export { Scene, Scenes, useActiveScene } from './Scenes.js';
+export { useExoApp } from './useExoApp.js';
+export { useExoApplication } from './useExoApplication.js';
+export { useScene } from './useScene.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}

package/dist/esm/useExoApp.d.ts

@@ -0,0 +1,17 @@
+import type { Application } from '@codexo/exojs';
+/**
+ * Returns the {@link Application} instance from the nearest {@link ExoCanvas}
+ * ancestor. Throws an informative error when called outside of an
+ * `<ExoCanvas>` tree.
+ *
+ * @throws {Error} When no `<ExoCanvas>` ancestor is present.
+ *
+ * @example
+ * ```tsx
+ * function HudOverlay() {
+ *   const app = useExoApp();
+ *   return <span>Frame: {app.frameCount}</span>;
+ * }
+ * ```
+ */
+export declare function useExoApp(): Application;

package/dist/esm/useExoApp.js

@@ -0,0 +1,27 @@
+import { useExoContext } from './ExoContext.js';
+
+/**
+ * Returns the {@link Application} instance from the nearest {@link ExoCanvas}
+ * ancestor. Throws an informative error when called outside of an
+ * `<ExoCanvas>` tree.
+ *
+ * @throws {Error} When no `<ExoCanvas>` ancestor is present.
+ *
+ * @example
+ * ```tsx
+ * function HudOverlay() {
+ *   const app = useExoApp();
+ *   return <span>Frame: {app.frameCount}</span>;
+ * }
+ * ```
+ */
+function useExoApp() {
+    const app = useExoContext();
+    if (app === null) {
+        throw new Error('useExoApp must be used inside an <ExoCanvas> component.');
+    }
+    return app;
+}
+
+export { useExoApp };
+//# sourceMappingURL=useExoApp.js.map

package/dist/esm/useExoApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExoApp.js","sources":["../../../src/useExoApp.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;AAcG;SACa,SAAS,GAAA;AACvB,IAAA,MAAM,GAAG,GAAG,aAAa,EAAE;AAE3B,IAAA,IAAI,GAAG,KAAK,IAAI,EAAE;AAChB,QAAA,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC;IAC5E;AAEA,IAAA,OAAO,GAAG;AACZ;;;;"}

package/dist/esm/useExoApplication.d.ts

@@ -0,0 +1,57 @@
+import { Application, type ApplicationOptions, type CanvasApplicationOptions } from '@codexo/exojs';
+import { type Ref } from 'react';
+/**
+ * Options for {@link useExoApplication} / {@link import('./ExoCanvas').ExoCanvas}.
+ *
+ * Same as {@link ApplicationOptions} but the `canvas.element` and `canvas.mount`
+ * fields are managed for you (the Application binds to the canvas the hook
+ * references), so they are omitted. You may still pass
+ * `canvas.width`/`height`/`sizingMode`/etc.
+ */
+export type ExoApplicationOptions = Omit<ApplicationOptions, 'canvas'> & {
+    readonly canvas?: Omit<CanvasApplicationOptions, 'element' | 'mount'>;
+};
+/** Return value of {@link useExoApplication}. */
+export interface UseExoApplicationResult {
+    /** The Application instance, or `null` until it has been created. */
+    readonly app: Application | null;
+    /**
+     * Attach this to the `<canvas>` element the Application should bind to. Typed
+     * as `Ref` (not `RefObject`) so the same code type-checks against both
+     * `@types/react` 18 and 19, whose `useRef`/`RefObject` nullability differ.
+     */
+    readonly canvasRef: Ref<HTMLCanvasElement>;
+}
+/**
+ * Creates and owns an ExoJS {@link Application}, binding it to a `<canvas>` you
+ * render yourself and attach the returned `canvasRef` to. The hook renders no
+ * DOM of its own — you keep full control over the canvas element, its container,
+ * and its styling.
+ *
+ * ```tsx
+ * function Game() {
+ *   const { app, canvasRef } = useExoApplication({ canvas: { width: 800, height: 600 } });
+ *   return <canvas ref={canvasRef} className="game" />;
+ * }
+ * ```
+ *
+ * **Reactivity model.** The Application is recreated only when an *identity*
+ * option changes — currently the render `backend` (you cannot hot-swap WebGL2 ↔
+ * WebGPU). All other supported options are applied *live* without tearing the
+ * app down:
+ *
+ * - `canvas.width` / `canvas.height` → `app.resize(...)`
+ * - `canvas.sizingMode` → `app.sizingMode`
+ * - `clearColor` → `app.clearColor`
+ *
+ * Options without a live setter (e.g. `canvas.pixelRatio`, `seed`, `extensions`)
+ * are captured at creation; change the `backend` or remount to apply them.
+ *
+ * Styling note: with the default `'fixed'` sizing mode the engine never touches
+ * the canvas CSS, so you may style it freely. The `'fit'`/`'shrink'`/`'letterbox'`
+ * modes manage `canvas.style` themselves — don't fight them with a `style` prop.
+ *
+ * @param options - Application options (the canvas element is the one you render).
+ * @param onReady - Called once each time an Application is created.
+ */
+export declare function useExoApplication(options?: ExoApplicationOptions, onReady?: (app: Application) => void): UseExoApplicationResult;

package/dist/esm/useExoApplication.js

@@ -0,0 +1,103 @@
+import { Application } from '@codexo/exojs';
+import { useRef, useState, useEffect } from 'react';
+
+/** Stable string key for the colour so the sync effect can depend on its value. */
+function colorKey(color) {
+    return color === undefined ? undefined : `${color.r},${color.g},${color.b},${color.a}`;
+}
+/**
+ * Creates and owns an ExoJS {@link Application}, binding it to a `<canvas>` you
+ * render yourself and attach the returned `canvasRef` to. The hook renders no
+ * DOM of its own — you keep full control over the canvas element, its container,
+ * and its styling.
+ *
+ * ```tsx
+ * function Game() {
+ *   const { app, canvasRef } = useExoApplication({ canvas: { width: 800, height: 600 } });
+ *   return <canvas ref={canvasRef} className="game" />;
+ * }
+ * ```
+ *
+ * **Reactivity model.** The Application is recreated only when an *identity*
+ * option changes — currently the render `backend` (you cannot hot-swap WebGL2 ↔
+ * WebGPU). All other supported options are applied *live* without tearing the
+ * app down:
+ *
+ * - `canvas.width` / `canvas.height` → `app.resize(...)`
+ * - `canvas.sizingMode` → `app.sizingMode`
+ * - `clearColor` → `app.clearColor`
+ *
+ * Options without a live setter (e.g. `canvas.pixelRatio`, `seed`, `extensions`)
+ * are captured at creation; change the `backend` or remount to apply them.
+ *
+ * Styling note: with the default `'fixed'` sizing mode the engine never touches
+ * the canvas CSS, so you may style it freely. The `'fit'`/`'shrink'`/`'letterbox'`
+ * modes manage `canvas.style` themselves — don't fight them with a `style` prop.
+ *
+ * @param options - Application options (the canvas element is the one you render).
+ * @param onReady - Called once each time an Application is created.
+ */
+function useExoApplication(options, onReady) {
+    const canvasRef = useRef(null);
+    const [app, setApp] = useState(null);
+    // Latest onReady without retriggering the lifecycle effect. Updated in an
+    // effect (not during render) so the ref-write happens after commit.
+    const onReadyRef = useRef(onReady);
+    useEffect(() => {
+        onReadyRef.current = onReady;
+    });
+    // Identity: only the backend type forces a full recreation.
+    const backendKey = options?.backend?.type ?? 'auto';
+    // ── Lifecycle: create on mount / recreate on backend change ───────────────
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas) {
+            return;
+        }
+        // Bind to the React-rendered canvas. The engine never removes a canvas it
+        // did not create (Application.destroy leaves it in the DOM), so React stays
+        // the sole owner of the element's lifecycle.
+        const application = new Application({
+            ...options,
+            canvas: { ...options?.canvas, element: canvas },
+        });
+        setApp(application);
+        onReadyRef.current?.(application);
+        return () => {
+            application.destroy();
+            setApp(null);
+        };
+        // Recreate only when the backend identity changes; live options are synced
+        // by the effects below. `options` is intentionally read at (re)create time.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [backendKey]);
+    // ── Live sync: size ───────────────────────────────────────────────────────
+    const width = options?.canvas?.width;
+    const height = options?.canvas?.height;
+    useEffect(() => {
+        if (app !== null && width !== undefined && height !== undefined) {
+            app.resize(width, height);
+        }
+    }, [app, width, height]);
+    // ── Live sync: sizing mode ────────────────────────────────────────────────
+    const sizingMode = options?.canvas?.sizingMode;
+    useEffect(() => {
+        if (app !== null && sizingMode !== undefined) {
+            app.sizingMode = sizingMode;
+        }
+    }, [app, sizingMode]);
+    // ── Live sync: clear colour ───────────────────────────────────────────────
+    const clearColor = options?.clearColor;
+    const clearKey = colorKey(clearColor);
+    useEffect(() => {
+        if (app !== null && clearColor !== undefined) {
+            app.clearColor = clearColor;
+        }
+        // clearColor identity is unstable; depend on its value key instead.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [app, clearKey]);
+    return { app, canvasRef };
+}
+
+export { useExoApplication };
+//# sourceMappingURL=useExoApplication.js.map

package/dist/esm/useExoApplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExoApplication.js","sources":["../../../src/useExoApplication.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AA2BA;AACA,SAAS,QAAQ,CAAC,KAAwB,EAAA;IACxC,OAAO,KAAK,KAAK,SAAS,GAAG,SAAS,GAAG,CAAA,EAAG,KAAK,CAAC,CAAC,CAAA,CAAA,EAAI,KAAK,CAAC,CAAC,CAAA,CAAA,EAAI,KAAK,CAAC,CAAC,CAAA,CAAA,EAAI,KAAK,CAAC,CAAC,CAAA,CAAE;AACxF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BG;AACG,SAAU,iBAAiB,CAC/B,OAA+B,EAC/B,OAAoC,EAAA;AAEpC,IAAA,MAAM,SAAS,GAAG,MAAM,CAAoB,IAAI,CAAC;IACjD,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAqB,IAAI,CAAC;;;AAIxD,IAAA,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC;IAClC,SAAS,CAAC,MAAK;AACb,QAAA,UAAU,CAAC,OAAO,GAAG,OAAO;AAC9B,IAAA,CAAC,CAAC;;IAGF,MAAM,UAAU,GAAG,OAAO,EAAE,OAAO,EAAE,IAAI,IAAI,MAAM;;IAGnD,SAAS,CAAC,MAAK;AACb,QAAA,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO;QAChC,IAAI,CAAC,MAAM,EAAE;YACX;QACF;;;;AAKA,QAAA,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC;AAClC,YAAA,GAAG,OAAO;YACV,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE;AAChD,SAAA,CAAC;QAEF,MAAM,CAAC,WAAW,CAAC;AACnB,QAAA,UAAU,CAAC,OAAO,GAAG,WAAW,CAAC;AAEjC,QAAA,OAAO,MAAK;YACV,WAAW,CAAC,OAAO,EAAE;YACrB,MAAM,CAAC,IAAI,CAAC;AACd,QAAA,CAAC;;;;AAIH,IAAA,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;;AAGhB,IAAA,MAAM,KAAK,GAAG,OAAO,EAAE,MAAM,EAAE,KAAK;AACpC,IAAA,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM;IACtC,SAAS,CAAC,MAAK;AACb,QAAA,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE;AAC/D,YAAA,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;QAC3B;IACF,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;;AAGxB,IAAA,MAAM,UAAU,GAAG,OAAO,EAAE,MAAM,EAAE,UAAU;IAC9C,SAAS,CAAC,MAAK;QACb,IAAI,GAAG,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,EAAE;AAC5C,YAAA,GAAG,CAAC,UAAU,GAAG,UAAU;QAC7B;AACF,IAAA,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;;AAGrB,IAAA,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU;AACtC,IAAA,MAAM,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC;IACrC,SAAS,CAAC,MAAK;QACb,IAAI,GAAG,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,EAAE;AAC5C,YAAA,GAAG,CAAC,UAAU,GAAG,UAAU;QAC7B;;;AAGF,IAAA,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAEnB,IAAA,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE;AAC3B;;;;"}

package/dist/esm/useScene.d.ts

@@ -0,0 +1,29 @@
+import { type Scene } from '@codexo/exojs';
+import { type DependencyList } from 'react';
+/**
+ * Creates an instance of `SceneClass`, activates it on the ExoJS
+ * {@link Application}, and returns it once the scene is live.
+ *
+ * On first call (engine not yet started) this hook calls `app.start(scene)`,
+ * which initializes the render backend and begins the per-frame loop. On
+ * subsequent dep-change remounts it calls `app.scene.setScene(scene)` to
+ * switch scenes without restarting the engine.
+ *
+ * The scene is cleared (`setScene(null)`) when the component unmounts or
+ * when `deps` change — mirroring `useEffect` semantics.
+ *
+ * @param SceneClass - Constructor for the scene to instantiate.
+ * @param deps - Extra deps that trigger scene replacement when changed, in
+ *   addition to the stable `app` reference (same semantics as `useEffect`).
+ * @returns The active scene instance, or `null` while it is loading.
+ *
+ * @example
+ * ```tsx
+ * function GameScreen() {
+ *   const scene = useScene(MyGameScene);
+ *   if (!scene) return null;
+ *   return <ScoreHud scene={scene} />;
+ * }
+ * ```
+ */
+export declare function useScene<T extends Scene>(SceneClass: new () => T, deps?: DependencyList): T | null;

package/dist/esm/useScene.js

@@ -0,0 +1,67 @@
+import { ApplicationStatus } from '@codexo/exojs';
+import { useState, useEffect } from 'react';
+import { useExoApp } from './useExoApp.js';
+
+/**
+ * Creates an instance of `SceneClass`, activates it on the ExoJS
+ * {@link Application}, and returns it once the scene is live.
+ *
+ * On first call (engine not yet started) this hook calls `app.start(scene)`,
+ * which initializes the render backend and begins the per-frame loop. On
+ * subsequent dep-change remounts it calls `app.scene.setScene(scene)` to
+ * switch scenes without restarting the engine.
+ *
+ * The scene is cleared (`setScene(null)`) when the component unmounts or
+ * when `deps` change — mirroring `useEffect` semantics.
+ *
+ * @param SceneClass - Constructor for the scene to instantiate.
+ * @param deps - Extra deps that trigger scene replacement when changed, in
+ *   addition to the stable `app` reference (same semantics as `useEffect`).
+ * @returns The active scene instance, or `null` while it is loading.
+ *
+ * @example
+ * ```tsx
+ * function GameScreen() {
+ *   const scene = useScene(MyGameScene);
+ *   if (!scene) return null;
+ *   return <ScoreHud scene={scene} />;
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+function useScene(SceneClass, deps = []) {
+    const app = useExoApp();
+    const [scene, setScene] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        const s = new SceneClass();
+        const apply = async () => {
+            if (app.status === ApplicationStatus.Stopped) {
+                // First activation — initialize the backend and start the frame loop.
+                await app.start(s);
+            }
+            else {
+                // Engine already running — switch scenes without restarting.
+                await app.scene.setScene(s);
+            }
+            if (!cancelled) {
+                setScene(s);
+            }
+        };
+        void apply();
+        return () => {
+            cancelled = true;
+            setScene(null);
+            // Best-effort scene clear; the Application.destroy() called by
+            // ExoCanvas cleanup will also handle any remaining active scene.
+            void app.scene.setScene(null);
+        };
+        // SceneClass is intentionally excluded from deps: a new class reference
+        // (e.g. inline arrow class) on every render would recreate the scene
+        // each frame. Pass an explicit deps array to react to changes.
+    }, [app, ...deps]);
+    return scene;
+}
+
+export { useScene };
+//# sourceMappingURL=useScene.js.map

package/dist/esm/useScene.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScene.js","sources":["../../../src/useScene.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACH;SACgB,QAAQ,CAAkB,UAAuB,EAAE,OAAuB,EAAE,EAAA;AAC1F,IAAA,MAAM,GAAG,GAAG,SAAS,EAAE;IACvB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAW,IAAI,CAAC;IAElD,SAAS,CAAC,MAAK;QACb,IAAI,SAAS,GAAG,KAAK;AACrB,QAAA,MAAM,CAAC,GAAG,IAAI,UAAU,EAAE;AAE1B,QAAA,MAAM,KAAK,GAAG,YAA0B;YACtC,IAAI,GAAG,CAAC,MAAM,KAAK,iBAAiB,CAAC,OAAO,EAAE;;AAE5C,gBAAA,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;YACpB;iBAAO;;gBAEL,MAAM,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC7B;YAEA,IAAI,CAAC,SAAS,EAAE;gBACd,QAAQ,CAAC,CAAC,CAAC;YACb;AACF,QAAA,CAAC;QAED,KAAK,KAAK,EAAE;AAEZ,QAAA,OAAO,MAAK;YACV,SAAS,GAAG,IAAI;YAChB,QAAQ,CAAC,IAAI,CAAC;;;YAGd,KAAK,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;AAC/B,QAAA,CAAC;;;;IAIH,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AAElB,IAAA,OAAO,KAAK;AACd;;;;"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@codexo/exojs-react",
+  "version": "0.14.0",
+  "description": "React integration for ExoJS.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Exoridus/ExoJS.git",
+    "directory": "packages/exojs-react"
+  },
+  "type": "module",
+  "main": "./dist/esm/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/esm/",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@codexo/exojs": "0.14.x",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@codexo/exojs": "0.14.0",
+    "@codexo/exojs-config": "0.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsx ../../node_modules/rollup/dist/bin/rollup -c --environment EXOJS_ENV:production",
+    "build:dev": "tsx ../../node_modules/rollup/dist/bin/rollup -c --environment EXOJS_ENV:development",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.{ts,tsx}\""
+  }
+}