@codexo/exojs-react 0.15.2 → 0.16.0

package/dist/esm/useExoApp.d.ts

@@ -6,7 +6,7 @@ import type { Application } from '@codexo/exojs';
  *
  * @throws {Error} When no `<ExoCanvas>` ancestor is present.
  *
- * `app.frameCount` is a plain getter updated by the engine's own frame loop —
+ * `app.frameCount` is a plain getter updated by the engine's own frame loop -
  * reading it here does not, on its own, make `HudOverlay` re-render. Pair it
  * with {@link import('./useSignal').useSignal} to subscribe to `app.onFrame`
  * and re-render on every dispatch.
@@ -20,4 +20,5 @@ import type { Application } from '@codexo/exojs';
  * }
  * ```
  */
-export declare function useExoApp(): Application;
+export declare const useExoApp: () => Application;
+//# sourceMappingURL=useExoApp.d.ts.map

package/dist/esm/useExoApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExoApp.d.ts","sourceRoot":"","sources":["../../src/useExoApp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS,QAAO,WAQ5B,CAAC"}

package/dist/esm/useExoApp.js

@@ -1,33 +1,33 @@
-import { useExoContext } from './ExoContext.js';
+import { useExoContext } from "./ExoContext.js";
 
+//#region src/useExoApp.ts
 /**
- * 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.
- *
- * `app.frameCount` is a plain getter updated by the engine's own frame loop —
- * reading it here does not, on its own, make `HudOverlay` re-render. Pair it
- * with {@link import('./useSignal').useSignal} to subscribe to `app.onFrame`
- * and re-render on every dispatch.
- *
- * @example
- * ```tsx
- * function HudOverlay() {
- *   const app = useExoApp();
- *   const frameCount = useSignal(app.onFrame, () => app.frameCount);
- *   return <span>Frame: {frameCount}</span>;
- * }
- * ```
- */
-function useExoApp() {
-    const app = useExoContext();
-    if (app === null) {
-        throw new Error('useExoApp must be used inside an <ExoCanvas> component.');
-    }
-    return app;
-}
+* 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.
+*
+* `app.frameCount` is a plain getter updated by the engine's own frame loop -
+* reading it here does not, on its own, make `HudOverlay` re-render. Pair it
+* with {@link import('./useSignal').useSignal} to subscribe to `app.onFrame`
+* and re-render on every dispatch.
+*
+* @example
+* ```tsx
+* function HudOverlay() {
+*   const app = useExoApp();
+*   const frameCount = useSignal(app.onFrame, () => app.frameCount);
+*   return <span>Frame: {frameCount}</span>;
+* }
+* ```
+*/
+const useExoApp = () => {
+	const app = useExoContext();
+	if (app === null) throw new Error("useExoApp must be used inside an <ExoCanvas> component.");
+	return app;
+};
 
+//#endregion
 export { useExoApp };
-//# sourceMappingURL=useExoApp.js.map
+//# sourceMappingURL=useExoApp.js.map

package/dist/esm/useExoApp.js.map

@@ -1 +1 @@
-{"version":3,"file":"useExoApp.js","sources":["../../../src/useExoApp.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;;;;;;;AAoBG;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;;;;"}
+{"version":3,"file":"useExoApp.js","names":[],"sources":["../../src/useExoApp.ts"],"sourcesContent":["import type { Application } from '@codexo/exojs';\n\nimport { useExoContext } from './ExoContext';\n\n/**\n * Returns the {@link Application} instance from the nearest {@link ExoCanvas}\n * ancestor. Throws an informative error when called outside of an\n * `<ExoCanvas>` tree.\n *\n * @throws {Error} When no `<ExoCanvas>` ancestor is present.\n *\n * `app.frameCount` is a plain getter updated by the engine's own frame loop -\n * reading it here does not, on its own, make `HudOverlay` re-render. Pair it\n * with {@link import('./useSignal').useSignal} to subscribe to `app.onFrame`\n * and re-render on every dispatch.\n *\n * @example\n * ```tsx\n * function HudOverlay() {\n *   const app = useExoApp();\n *   const frameCount = useSignal(app.onFrame, () => app.frameCount);\n *   return <span>Frame: {frameCount}</span>;\n * }\n * ```\n */\nexport const useExoApp = (): Application => {\n  const app = useExoContext();\n\n  if (app === null) {\n    throw new Error('useExoApp must be used inside an <ExoCanvas> component.');\n  }\n\n  return app;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,kBAA+B;CAC1C,MAAM,MAAM,cAAc;CAE1B,IAAI,QAAQ,MACV,MAAM,IAAI,MAAM,yDAAyD;CAG3E,OAAO;AACT"}

package/dist/esm/useExoApplication.d.ts

@@ -6,7 +6,7 @@ import { type Ref } from 'react';
  * 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.
+ * `canvas.width`/`height`/`sizing`/etc.
  */
 export type ExoApplicationOptions = Omit<ApplicationOptions, 'canvas'> & {
     readonly canvas?: Omit<CanvasApplicationOptions, 'element' | 'mount'>;
@@ -25,7 +25,7 @@ export interface UseExoApplicationResult {
 /**
  * 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,
+ * DOM of its own - you keep full control over the canvas element, its container,
  * and its styling.
  *
  * ```tsx
@@ -36,20 +36,24 @@ export interface UseExoApplicationResult {
  * ```
  *
  * **Reactivity model.** The Application is recreated only when an *identity*
- * option changes — currently the render `backend` (you cannot hot-swap WebGL2 ↔
+ * 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.
+ * `canvas.sizing` is captured at creation too, deliberately: a policy is an
+ * object, so a new instance on every render would detach and re-attach the
+ * previous one each time. Assign `app.sizing` yourself to switch strategies.
+ *
+ * Styling note: with no `canvas.sizing` the engine keeps the canvas at the base
+ * resolution and writes only that size, so you may style it freely. A sizing
+ * policy owns the canvas's `width`/`height` styles - don't fight it 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.
@@ -57,4 +61,5 @@ export interface UseExoApplicationResult {
  *   init/scene-load failures) while an Application exists. Re-subscribed
  *   automatically whenever the Application is (re)created.
  */
-export declare function useExoApplication(options?: ExoApplicationOptions, onReady?: (app: Application) => void, onError?: (error: unknown) => void): UseExoApplicationResult;
+export declare const useExoApplication: (options?: ExoApplicationOptions, onReady?: (app: Application) => void, onError?: (error: unknown) => void) => UseExoApplicationResult;
+//# sourceMappingURL=useExoApplication.d.ts.map

package/dist/esm/useExoApplication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExoApplication.d.ts","sourceRoot":"","sources":["../../src/useExoApplication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAAc,MAAM,eAAe,CAAC;AAChH,OAAO,EAAE,KAAK,GAAG,EAA+B,MAAM,OAAO,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAAG;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC;CACvE,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC;CAC5C;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,qBAAqB,EAC/B,UAAU,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,EACpC,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KACjC,uBAwFF,CAAC"}

package/dist/esm/useExoApplication.js

@@ -1,124 +1,107 @@
-import { Application } from '@codexo/exojs';
-import { useRef, useState, useEffect } from 'react';
+import { useEffect, useRef, useState } from "react";
+import { Application } from "@codexo/exojs";
 
+//#region src/useExoApplication.ts
 /** 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}`;
-}
+const colorKey = (color) => color === void 0 ? void 0 : `${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.
- * @param onError - Called for every {@link Application.onError} dispatch (async
- *   init/scene-load failures) while an Application exists. Re-subscribed
- *   automatically whenever the Application is (re)created.
- */
-function useExoApplication(options, onReady, onError) {
-    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;
-    });
-    // Latest onError without retriggering the subscribe effect below.
-    const onErrorRef = useRef(onError);
-    useEffect(() => {
-        onErrorRef.current = onError;
-    });
-    // 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: error reporting ─────────────────────────────────────────────
-    useEffect(() => {
-        if (app === null) {
-            return;
-        }
-        const handleError = (error) => {
-            onErrorRef.current?.(error);
-        };
-        app.onError.add(handleError);
-        return () => {
-            app.onError.remove(handleError);
-        };
-    }, [app]);
-    // ── 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 };
-}
+* 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(...)`
+* - `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.
+*
+* `canvas.sizing` is captured at creation too, deliberately: a policy is an
+* object, so a new instance on every render would detach and re-attach the
+* previous one each time. Assign `app.sizing` yourself to switch strategies.
+*
+* Styling note: with no `canvas.sizing` the engine keeps the canvas at the base
+* resolution and writes only that size, so you may style it freely. A sizing
+* policy owns the canvas's `width`/`height` styles - don't fight it 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.
+* @param onError - Called for every {@link Application.onError} dispatch (async
+*   init/scene-load failures) while an Application exists. Re-subscribed
+*   automatically whenever the Application is (re)created.
+*/
+const useExoApplication = (options, onReady, onError) => {
+	const canvasRef = useRef(null);
+	const [app, setApp] = useState(null);
+	const onReadyRef = useRef(onReady);
+	useEffect(() => {
+		onReadyRef.current = onReady;
+	});
+	const onErrorRef = useRef(onError);
+	useEffect(() => {
+		onErrorRef.current = onError;
+	});
+	const backendKey = options?.backend?.type ?? "auto";
+	useEffect(() => {
+		const canvas = canvasRef.current;
+		if (!canvas) return;
+		const application = new Application({
+			...options,
+			canvas: {
+				...options?.canvas,
+				element: canvas
+			}
+		});
+		setApp(application);
+		onReadyRef.current?.(application);
+		return () => {
+			application.destroy();
+			setApp(null);
+		};
+	}, [backendKey]);
+	useEffect(() => {
+		if (app === null) return;
+		const handleError = (error) => {
+			onErrorRef.current?.(error);
+		};
+		app.onError.add(handleError);
+		return () => {
+			app.onError.remove(handleError);
+		};
+	}, [app]);
+	const width = options?.canvas?.width;
+	const height = options?.canvas?.height;
+	useEffect(() => {
+		if (app !== null && width !== void 0 && height !== void 0) app.resize(width, height);
+	}, [
+		app,
+		width,
+		height
+	]);
+	const clearColor = options?.clearColor;
+	const clearKey = colorKey(clearColor);
+	useEffect(() => {
+		if (app !== null && clearColor !== void 0) app.clearColor = clearColor;
+	}, [app, clearKey]);
+	return {
+		app,
+		canvasRef
+	};
+};
 
+//#endregion
 export { useExoApplication };
-//# sourceMappingURL=useExoApplication.js.map
+//# sourceMappingURL=useExoApplication.js.map

package/dist/esm/useExoApplication.js.map

@@ -1 +1 @@
-{"version":3,"file":"useExoApplication.js","sources":["../../../src/useExoApplication.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"useExoApplication.js","names":[],"sources":["../../src/useExoApplication.ts"],"sourcesContent":["import { Application, type ApplicationOptions, type CanvasApplicationOptions, type Color } from '@codexo/exojs';\nimport { type Ref, useEffect, useRef, useState } from 'react';\n\n/**\n * Options for {@link useExoApplication} / {@link import('./ExoCanvas').ExoCanvas}.\n *\n * Same as {@link ApplicationOptions} but the `canvas.element` and `canvas.mount`\n * fields are managed for you (the Application binds to the canvas the hook\n * references), so they are omitted. You may still pass\n * `canvas.width`/`height`/`sizing`/etc.\n */\nexport type ExoApplicationOptions = Omit<ApplicationOptions, 'canvas'> & {\n  readonly canvas?: Omit<CanvasApplicationOptions, 'element' | 'mount'>;\n};\n\n/** Return value of {@link useExoApplication}. */\nexport interface UseExoApplicationResult {\n  /** The Application instance, or `null` until it has been created. */\n  readonly app: Application | null;\n  /**\n   * Attach this to the `<canvas>` element the Application should bind to. Typed\n   * as `Ref` (not `RefObject`) so the same code type-checks against both\n   * `@types/react` 18 and 19, whose `useRef`/`RefObject` nullability differ.\n   */\n  readonly canvasRef: Ref<HTMLCanvasElement>;\n}\n\n/** Stable string key for the colour so the sync effect can depend on its value. */\nconst colorKey = (color: Color | undefined): string | undefined => (color === undefined ? undefined : `${color.r},${color.g},${color.b},${color.a}`);\n\n/**\n * Creates and owns an ExoJS {@link Application}, binding it to a `<canvas>` you\n * render yourself and attach the returned `canvasRef` to. The hook renders no\n * DOM of its own - you keep full control over the canvas element, its container,\n * and its styling.\n *\n * ```tsx\n * function Game() {\n *   const { app, canvasRef } = useExoApplication({ canvas: { width: 800, height: 600 } });\n *   return <canvas ref={canvasRef} className=\"game\" />;\n * }\n * ```\n *\n * **Reactivity model.** The Application is recreated only when an *identity*\n * option changes - currently the render `backend` (you cannot hot-swap WebGL2 ↔\n * WebGPU). All other supported options are applied *live* without tearing the\n * app down:\n *\n * - `canvas.width` / `canvas.height` → `app.resize(...)`\n * - `clearColor` → `app.clearColor`\n *\n * Options without a live setter (e.g. `canvas.pixelRatio`, `seed`, `extensions`)\n * are captured at creation; change the `backend` or remount to apply them.\n *\n * `canvas.sizing` is captured at creation too, deliberately: a policy is an\n * object, so a new instance on every render would detach and re-attach the\n * previous one each time. Assign `app.sizing` yourself to switch strategies.\n *\n * Styling note: with no `canvas.sizing` the engine keeps the canvas at the base\n * resolution and writes only that size, so you may style it freely. A sizing\n * policy owns the canvas's `width`/`height` styles - don't fight it with a\n * `style` prop.\n *\n * @param options - Application options (the canvas element is the one you render).\n * @param onReady - Called once each time an Application is created.\n * @param onError - Called for every {@link Application.onError} dispatch (async\n *   init/scene-load failures) while an Application exists. Re-subscribed\n *   automatically whenever the Application is (re)created.\n */\nexport const useExoApplication = (\n  options?: ExoApplicationOptions,\n  onReady?: (app: Application) => void,\n  onError?: (error: unknown) => void,\n): UseExoApplicationResult => {\n  const canvasRef = useRef<HTMLCanvasElement>(null);\n  const [app, setApp] = useState<Application | null>(null);\n\n  // Latest onReady without retriggering the lifecycle effect. Updated in an\n  // effect (not during render) so the ref-write happens after commit.\n  const onReadyRef = useRef(onReady);\n  useEffect(() => {\n    onReadyRef.current = onReady;\n  });\n\n  // Latest onError without retriggering the subscribe effect below.\n  const onErrorRef = useRef(onError);\n  useEffect(() => {\n    onErrorRef.current = onError;\n  });\n\n  // Identity: only the backend type forces a full recreation.\n  const backendKey = options?.backend?.type ?? 'auto';\n\n  // ── Lifecycle: create on mount / recreate on backend change ───────────────\n  useEffect(() => {\n    const canvas = canvasRef.current;\n    if (!canvas) {\n      return;\n    }\n\n    // Bind to the React-rendered canvas. The engine never removes a canvas it\n    // did not create (Application.destroy leaves it in the DOM), so React stays\n    // the sole owner of the element's lifecycle.\n    const application = new Application({\n      ...options,\n      canvas: { ...options?.canvas, element: canvas },\n    });\n\n    setApp(application);\n    onReadyRef.current?.(application);\n\n    return () => {\n      // A React cleanup function cannot await, and teardown failures already\n      // travel through the application's own error pipeline - so the Promise\n      // is deliberately dropped rather than reported a second time here.\n      void application.destroy();\n      setApp(null);\n    };\n    // Recreate only when the backend identity changes; live options are synced\n    // by the effects below. `options` is intentionally read at (re)create time.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [backendKey]);\n\n  // ── Live sync: error reporting ─────────────────────────────────────────────\n  useEffect(() => {\n    if (app === null) {\n      return;\n    }\n\n    const handleError = (error: Error): void => {\n      onErrorRef.current?.(error);\n    };\n\n    app.onError.add(handleError);\n\n    return () => {\n      app.onError.remove(handleError);\n    };\n  }, [app]);\n\n  // ── Live sync: size ───────────────────────────────────────────────────────\n  const width = options?.canvas?.width;\n  const height = options?.canvas?.height;\n  useEffect(() => {\n    if (app !== null && width !== undefined && height !== undefined) {\n      app.resize(width, height);\n    }\n  }, [app, width, height]);\n\n  // ── Live sync: clear colour ───────────────────────────────────────────────\n  const clearColor = options?.clearColor;\n  const clearKey = colorKey(clearColor);\n  useEffect(() => {\n    if (app !== null && clearColor !== undefined) {\n      app.clearColor = clearColor;\n    }\n    // clearColor identity is unstable; depend on its value key instead.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [app, clearKey]);\n\n  return { app, canvasRef };\n};\n"],"mappings":";;;;;AA4BA,MAAM,YAAY,UAAkD,UAAU,SAAY,SAAY,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyChJ,MAAa,qBACX,SACA,SACA,YAC4B;CAC5B,MAAM,YAAY,OAA0B,IAAI;CAChD,MAAM,CAAC,KAAK,UAAU,SAA6B,IAAI;CAIvD,MAAM,aAAa,OAAO,OAAO;CACjC,gBAAgB;EACd,WAAW,UAAU;CACvB,CAAC;CAGD,MAAM,aAAa,OAAO,OAAO;CACjC,gBAAgB;EACd,WAAW,UAAU;CACvB,CAAC;CAGD,MAAM,aAAa,SAAS,SAAS,QAAQ;CAG7C,gBAAgB;EACd,MAAM,SAAS,UAAU;EACzB,IAAI,CAAC,QACH;EAMF,MAAM,cAAc,IAAI,YAAY;GAClC,GAAG;GACH,QAAQ;IAAE,GAAG,SAAS;IAAQ,SAAS;GAAO;EAChD,CAAC;EAED,OAAO,WAAW;EAClB,WAAW,UAAU,WAAW;EAEhC,aAAa;GAIX,AAAK,YAAY,QAAQ;GACzB,OAAO,IAAI;EACb;CAIF,GAAG,CAAC,UAAU,CAAC;CAGf,gBAAgB;EACd,IAAI,QAAQ,MACV;EAGF,MAAM,eAAe,UAAuB;GAC1C,WAAW,UAAU,KAAK;EAC5B;EAEA,IAAI,QAAQ,IAAI,WAAW;EAE3B,aAAa;GACX,IAAI,QAAQ,OAAO,WAAW;EAChC;CACF,GAAG,CAAC,GAAG,CAAC;CAGR,MAAM,QAAQ,SAAS,QAAQ;CAC/B,MAAM,SAAS,SAAS,QAAQ;CAChC,gBAAgB;EACd,IAAI,QAAQ,QAAQ,UAAU,UAAa,WAAW,QACpD,IAAI,OAAO,OAAO,MAAM;CAE5B,GAAG;EAAC;EAAK;EAAO;CAAM,CAAC;CAGvB,MAAM,aAAa,SAAS;CAC5B,MAAM,WAAW,SAAS,UAAU;CACpC,gBAAgB;EACd,IAAI,QAAQ,QAAQ,eAAe,QACjC,IAAI,aAAa;CAIrB,GAAG,CAAC,KAAK,QAAQ,CAAC;CAElB,OAAO;EAAE;EAAK;CAAU;AAC1B"}

package/dist/esm/useScene.d.ts

@@ -1,24 +1,30 @@
 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.
+ * Activates `SceneClass` on the ExoJS {@link Application} and returns the
+ * resulting instance once it is live. `SceneClass` must be registered in
+ * `ApplicationOptions.scenes` (passed to {@link import('./useExoApplication').useExoApplication}
+ * / {@link import('./ExoCanvas').ExoCanvas}) - unregistered targets reject in
+ * development builds.
  *
- * On first call (engine not yet started) this hook calls `app.start(scene)`,
+ * On first call (engine not yet started) this hook calls `app.start(SceneClass)`,
  * 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.
+ * subsequent dep-change remounts it calls `app.scenes.change(SceneClass)` to
+ * switch scenes without restarting the engine, constructing a fresh instance.
  *
- * The scene is cleared (`setScene(null)`) when the component unmounts or
- * when `deps` change — mirroring `useEffect` semantics.
+ * Effects that run while startup is still in flight - React StrictMode
+ * double-mounts every effect in development - join that `app.start()` call
+ * instead of racing a second navigation against it, and only activate
+ * `SceneClass` afterwards if startup did not already leave it active. A
+ * StrictMode double mount therefore activates the scene exactly once.
  *
- * A failure in `app.start()`/`app.scene.setScene()` (e.g. a scene's `onLoad`
+ * A failure in `app.start()`/`app.scenes.change()` (e.g. a scene's `load()`
  * rejects) is caught and routed to {@link Application.onError} rather than
- * left as an unhandled promise rejection — subscribe via
+ * left as an unhandled promise rejection - subscribe via
  * `app.onError.add(...)` or the {@link import('./ExoCanvas').ExoCanvas}
  * `onError` prop to observe it.
  *
- * @param SceneClass - Constructor for the scene to instantiate.
+ * @param SceneClass - Constructor for the scene to activate.
  * @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.
@@ -32,4 +38,5 @@ import { type DependencyList } from 'react';
  * }
  * ```
  */
-export declare function useScene<T extends Scene>(SceneClass: new () => T, deps?: DependencyList): T | null;
+export declare const useScene: <T extends Scene>(SceneClass: new () => T, deps?: DependencyList) => T | null;
+//# sourceMappingURL=useScene.d.ts.map

package/dist/esm/useScene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScene.d.ts","sourceRoot":"","sources":["../../src/useScene.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,KAAK,EAAyB,MAAM,eAAe,CAAC;AACpF,OAAO,EAAE,KAAK,cAAc,EAA+B,MAAM,OAAO,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,KAAK,EAAE,YAAY,UAAU,CAAC,EAAE,OAAM,cAAmB,KAAG,CAAC,GAAG,IAkFlG,CAAC"}