r3f-scene-router 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# r3f-scene-router
+
+**Declarative scene router for React Three Fiber — one persistent Canvas, many scenes.**
+
+Define your 3D scenes with camera positions, controls, and post-processing effects. The router handles smooth transitions between them while keeping the WebGL context alive.
+
+## Why
+
+React Three Fiber apps typically face a choice:
+- **One giant scene** with visibility toggling (complex, poor separation)
+- **Multiple Canvases** (each remounts the WebGL context — expensive, flickery)
+
+`r3f-scene-router` gives you the third option: **one Canvas, many scenes**, with declarative configuration for camera, controls, and effects per scene.
+
+## Quick Start
+
+```tsx
+import { SceneRouter, defineScenes } from "r3f-scene-router";
+import { useState } from "react";
+
+const scenes = defineScenes({
+  home: {
+    Component: HomeScene,
+    position: [0, 5, 10],
+    controls: "orbit",
+    postProcessing: { bloom: true, depthOfField: { focusDistance: 5 } }
+  },
+  gallery: {
+    Component: GalleryScene,
+    position: [0, 2, 0],
+    controls: "pointer-lock",
+    transition: { duration: 1.2 }
+  },
+  physics: {
+    Component: PhysicsScene,
+    position: [-20, 0, 0],
+    controls: "orbit",
+    postProcessing: { vignette: true }
+  }
+});
+
+function App() {
+  const [scene, setScene] = useState("home");
+
+  return (
+    <>
+      <nav>
+        <button onClick={() => setScene("home")}>Home</button>
+        <button onClick={() => setScene("gallery")}>Gallery</button>
+        <button onClick={() => setScene("physics")}>Physics</button>
+      </nav>
+      <SceneRouter scenes={scenes} activeScene={scene} />
+    </>
+  );
+}
+```
+
+## Features
+
+- **Smooth camera transitions** — lerp between positions/rotations with configurable easing
+- **Per-scene controls** — orbit, fly, trackball, pointer-lock, map, or none
+- **Per-scene post-processing** — bloom, depth-of-field, vignette (composable)
+- **Persistent Canvas** — WebGL context never remounts, no flicker
+- **Type-safe** — full TypeScript with `SceneConfig` interface
+- **Framework-agnostic routing** — bring your own URL strategy (Next.js, React Router, or plain state)
+- **Hooks** — `useScene()` for accessing config/navigation inside scenes
+
+## API
+
+### `defineScenes(config)`
+
+Helper to create a scene map with sensible defaults.
+
+### `<SceneRouter>`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `scenes` | `Map<string, SceneConfig>` | required | Scene definitions |
+| `activeScene` | `string` | required | Currently active scene key |
+| `fallback` | `string` | — | Scene to show if `activeScene` doesn't match |
+| `defaultTransition` | `TransitionConfig` | `{ duration: 0.8 }` | Default camera transition |
+| `defaultControls` | `ControlsType` | `"orbit"` | Default control scheme |
+| `shadows` | `boolean` | `true` | Enable shadows |
+
+### `SceneConfig`
+
+```typescript
+interface SceneConfig {
+  Component: () => JSX.Element;
+  position?: [number, number, number];
+  rotation?: [number, number, number];
+  fov?: number;
+  controls?: "orbit" | "fly" | "trackball" | "head" | "pointer-lock" | "map" | "none";
+  postProcessing?: {
+    bloom?: boolean | { intensity?: number; radius?: number };
+    depthOfField?: boolean | { focusDistance?: number; focusRange?: number; bokehScale?: number };
+    vignette?: boolean | { offset?: number; darkness?: number };
+  };
+  transition?: { duration?: number; easing?: string };
+  camera?: "perspective" | "orthographic";
+  meta?: Record<string, unknown>;
+}
+```
+
+### `useScene()`
+
+Hook for scene components to access routing context:
+
+```tsx
+function MyScene() {
+  const { activeScene, config, navigate, isTransitioning } = useScene();
+  return <mesh onClick={() => navigate("other-scene")} />;
+}
+```
+
+## Integration with URL Routing
+
+The router doesn't own the URL — you do. Wire it to any routing strategy:
+
+```tsx
+// Next.js
+const scene = useRouter().query.view as string || "home";
+
+// React Router
+const { scene } = useParams();
+
+// Plain state
+const [scene, setScene] = useState("home");
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type ControlsType = "orbit" | "fly" | "trackball" | "head" | "pointer-lock" | "map" | "none";
+interface PostProcessingConfig {
+    bloom?: boolean | {
+        intensity?: number;
+        radius?: number;
+    };
+    depthOfField?: boolean | {
+        focusDistance?: number;
+        focusRange?: number;
+        bokehScale?: number;
+    };
+    vignette?: boolean | {
+        offset?: number;
+        darkness?: number;
+    };
+}
+interface TransitionConfig {
+    /** Duration in seconds for camera position/rotation lerp */
+    duration?: number;
+    /** Easing function name */
+    easing?: "linear" | "easeInOut" | "easeIn" | "easeOut";
+    /** Whether to fade between scenes */
+    fade?: boolean;
+    /** Fade duration in seconds */
+    fadeDuration?: number;
+}
+interface SceneConfig {
+    /** The R3F component to render inside the canvas */
+    Component: () => JSX.Element;
+    /** Camera position [x, y, z] */
+    position?: [number, number, number];
+    /** Camera rotation [x, y, z] in radians */
+    rotation?: [number, number, number];
+    /** Camera field of view (perspective only) */
+    fov?: number;
+    /** Control scheme for this scene */
+    controls?: ControlsType;
+    /** Post-processing effects */
+    postProcessing?: PostProcessingConfig;
+    /** Transition configuration when entering this scene */
+    transition?: TransitionConfig;
+    /** Camera type */
+    camera?: "perspective" | "orthographic";
+    /** Optional scene-level metadata */
+    meta?: Record<string, unknown>;
+}
+interface SceneRouterProps {
+    /** Map of scene name → config */
+    scenes: Map<string, SceneConfig>;
+    /** The active scene key. Pass from your own URL/state management. */
+    activeScene: string;
+    /** Fallback scene if activeScene doesn't match */
+    fallback?: string;
+    /** Global default transition config */
+    defaultTransition?: TransitionConfig;
+    /** Global default controls type */
+    defaultControls?: ControlsType;
+    /** Callback when a scene component calls navigate() — use this to update your state/URL */
+    onNavigate?: (scene: string) => void;
+    /** Canvas props to forward */
+    shadows?: boolean;
+    /** Children rendered outside the scene (e.g., HUD, UI overlays) */
+    children?: ReactNode;
+}
+
+/**
+ * The main scene router. Renders a persistent Canvas and swaps scene
+ * content, camera, controls, and post-processing based on activeScene.
+ *
+ * @example
+ * ```tsx
+ * import { SceneRouter, defineScenes } from "r3f-scene-router";
+ *
+ * const scenes = defineScenes({
+ *   home: { Component: HomeScene, position: [0, 5, 10], controls: "orbit" },
+ *   gallery: { Component: GalleryScene, controls: "pointer-lock" }
+ * });
+ *
+ * function App() {
+ *   const [scene, setScene] = useState("home");
+ *   return <SceneRouter scenes={scenes} activeScene={scene} />;
+ * }
+ * ```
+ */
+declare function SceneRouter({ scenes, activeScene, fallback, defaultTransition, defaultControls, onNavigate, shadows, children, }: SceneRouterProps): react_jsx_runtime.JSX.Element;
+
+interface SceneContextValue {
+    activeScene: string;
+    config: SceneConfig | undefined;
+    navigate: (scene: string) => void;
+    isTransitioning: boolean;
+}
+/**
+ * Access the current scene configuration and navigation.
+ *
+ * @example
+ * ```tsx
+ * function MyScene() {
+ *   const { activeScene, navigate } = useScene();
+ *   return <mesh onClick={() => navigate("other-scene")} />;
+ * }
+ * ```
+ */
+declare function useScene(): SceneContextValue;
+/**
+ * Access transition state for building custom transitions.
+ */
+declare function useSceneTransition(): {
+    isTransitioning: boolean;
+    transition: TransitionConfig | undefined;
+};
+
+/**
+ * Define scenes declaratively.
+ *
+ * @example
+ * ```tsx
+ * const scenes = defineScenes({
+ *   home: {
+ *     Component: HomeScene,
+ *     position: [0, 5, 10],
+ *     controls: "orbit",
+ *     postProcessing: { bloom: true }
+ *   },
+ *   gallery: {
+ *     Component: GalleryScene,
+ *     position: [0, 2, 0],
+ *     controls: "pointer-lock",
+ *     postProcessing: { depthOfField: { focusDistance: 5 } }
+ *   }
+ * });
+ * ```
+ */
+declare function defineScenes(config: Record<string, SceneConfig>): Map<string, SceneConfig>;
+
+export { type ControlsType, type PostProcessingConfig, type SceneConfig, SceneRouter, type SceneRouterProps, type TransitionConfig, defineScenes, useScene, useSceneTransition };

package/dist/index.js

@@ -0,0 +1,203 @@
+// src/scene-router.tsx
+import { useState, useEffect, useRef as useRef2, useMemo, useCallback as useCallback2 } from "react";
+import { Canvas, useThree, useFrame } from "@react-three/fiber";
+import {
+  OrbitControls,
+  FlyControls,
+  TrackballControls,
+  MapControls,
+  PointerLockControls
+} from "@react-three/drei";
+import { EffectComposer, Bloom, DepthOfField, Vignette } from "@react-three/postprocessing";
+import * as THREE from "three";
+
+// src/hooks.ts
+import { createContext, useContext } from "react";
+var SceneContext = createContext({
+  activeScene: "",
+  config: void 0,
+  navigate: () => {
+  },
+  isTransitioning: false
+});
+function useScene() {
+  return useContext(SceneContext);
+}
+function useSceneTransition() {
+  const { isTransitioning, config } = useContext(SceneContext);
+  return {
+    isTransitioning,
+    transition: config?.transition
+  };
+}
+
+// src/scene-router.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function SceneCamera({ config, transitionDuration, sceneKey }) {
+  const { camera } = useThree();
+  const startPos = useRef2(new THREE.Vector3());
+  const startRot = useRef2(new THREE.Euler());
+  const endPos = useRef2(new THREE.Vector3());
+  const endRot = useRef2(new THREE.Euler());
+  const lastPos = useRef2(new THREE.Vector3());
+  const lastRot = useRef2(new THREE.Euler());
+  const progress = useRef2(1);
+  const initialized = useRef2(false);
+  if (!initialized.current) {
+    const [x, y, z] = config.position || [0, 0, 5];
+    camera.position.set(x, y, z);
+    const worldPos = config.meta?.worldPosition || [0, 0, 0];
+    camera.lookAt(worldPos[0], worldPos[1], worldPos[2]);
+    lastPos.current.set(x, y, z);
+    lastRot.current.set(camera.rotation.x, camera.rotation.y, camera.rotation.z);
+    initialized.current = true;
+  }
+  useEffect(() => {
+    if (progress.current === 1 && !initialized.current) return;
+    startPos.current.set(camera.position.x, camera.position.y, camera.position.z);
+    startRot.current.set(camera.rotation.x, camera.rotation.y, camera.rotation.z);
+    const [x, y, z] = config.position || [0, 0, 5];
+    endPos.current.set(x, y, z);
+    const worldPos = config.meta?.worldPosition || [0, 0, 0];
+    const tempCam = camera.clone();
+    tempCam.position.set(x, y, z);
+    tempCam.lookAt(worldPos[0], worldPos[1], worldPos[2]);
+    endRot.current.set(tempCam.rotation.x, tempCam.rotation.y, tempCam.rotation.z);
+    progress.current = 0;
+  }, [sceneKey]);
+  useFrame((_, delta) => {
+    if (progress.current >= 1) {
+      lastPos.current.set(camera.position.x, camera.position.y, camera.position.z);
+      lastRot.current.set(camera.rotation.x, camera.rotation.y, camera.rotation.z);
+      return;
+    }
+    const step = transitionDuration > 0 ? delta / transitionDuration : 1;
+    progress.current = Math.min(1, progress.current + step);
+    const t = easeInOut(progress.current);
+    camera.position.x = startPos.current.x + (endPos.current.x - startPos.current.x) * t;
+    camera.position.y = startPos.current.y + (endPos.current.y - startPos.current.y) * t;
+    camera.position.z = startPos.current.z + (endPos.current.z - startPos.current.z) * t;
+    camera.rotation.x = startRot.current.x + (endRot.current.x - startRot.current.x) * t;
+    camera.rotation.y = startRot.current.y + (endRot.current.y - startRot.current.y) * t;
+    camera.rotation.z = startRot.current.z + (endRot.current.z - startRot.current.z) * t;
+  }, -1);
+  return null;
+}
+function easeInOut(t) {
+  return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+}
+function SceneControls({ type, enabled, target }) {
+  const [ready, setReady] = useState(false);
+  const { camera } = useThree();
+  useEffect(() => {
+    if (enabled) {
+      const id = requestAnimationFrame(() => setReady(true));
+      return () => cancelAnimationFrame(id);
+    } else {
+      setReady(false);
+    }
+  }, [enabled]);
+  if (!ready) return null;
+  const orbitTarget = target || [0, 0, 0];
+  switch (type) {
+    case "orbit":
+      return /* @__PURE__ */ jsx(
+        OrbitControls,
+        {
+          target: orbitTarget,
+          enableDamping: false,
+          minPolarAngle: 0,
+          maxPolarAngle: Math.PI
+        }
+      );
+    case "fly":
+      return /* @__PURE__ */ jsx(FlyControls, { movementSpeed: 5, rollSpeed: 0.5 });
+    case "trackball":
+      return /* @__PURE__ */ jsx(TrackballControls, {});
+    case "map":
+      return /* @__PURE__ */ jsx(MapControls, { target: orbitTarget });
+    case "pointer-lock":
+      return /* @__PURE__ */ jsx(PointerLockControls, {});
+    case "head":
+      return /* @__PURE__ */ jsx(OrbitControls, {});
+    case "none":
+    default:
+      return null;
+  }
+}
+function ScenePostProcessing({ config }) {
+  if (!config) return null;
+  const hasAnyEffect = config.bloom || config.depthOfField || config.vignette;
+  if (!hasAnyEffect) return null;
+  const bloomProps = config.bloom === true ? { intensity: 1, radius: 0 } : typeof config.bloom === "object" ? config.bloom : void 0;
+  const dofProps = config.depthOfField === true ? { focusDistance: 2, focusRange: 1, bokehScale: 5 } : typeof config.depthOfField === "object" ? config.depthOfField : void 0;
+  const vignetteProps = config.vignette === true ? { offset: 0.3, darkness: 0.7 } : typeof config.vignette === "object" ? config.vignette : void 0;
+  const effects = [];
+  if (dofProps) effects.push(/* @__PURE__ */ jsx(DepthOfField, { ...dofProps }, "dof"));
+  if (bloomProps) effects.push(/* @__PURE__ */ jsx(Bloom, { ...bloomProps }, "bloom"));
+  if (vignetteProps) effects.push(/* @__PURE__ */ jsx(Vignette, { ...vignetteProps }, "vignette"));
+  return /* @__PURE__ */ jsx(EffectComposer, { children: effects.filter(Boolean) });
+}
+function SceneRouter({
+  scenes,
+  activeScene,
+  fallback,
+  defaultTransition = { duration: 0.8, easing: "easeInOut" },
+  defaultControls = "orbit",
+  onNavigate,
+  shadows = true,
+  children
+}) {
+  const [isTransitioning, setIsTransitioning] = useState(false);
+  const config = scenes.get(activeScene) || (fallback ? scenes.get(fallback) : void 0);
+  const controls = config?.controls || defaultControls;
+  const transitionDuration = config?.transition?.duration ?? defaultTransition.duration ?? 0.8;
+  const navigate = useCallback2((scene) => {
+    setIsTransitioning(true);
+    setTimeout(() => setIsTransitioning(false), transitionDuration * 1e3);
+    if (onNavigate) onNavigate(scene);
+  }, [transitionDuration, onNavigate]);
+  useEffect(() => {
+    setIsTransitioning(true);
+    const timer = setTimeout(() => setIsTransitioning(false), transitionDuration * 1e3);
+    return () => clearTimeout(timer);
+  }, [activeScene, transitionDuration]);
+  const contextValue = useMemo(() => ({
+    activeScene,
+    config,
+    navigate,
+    isTransitioning
+  }), [activeScene, config, navigate, isTransitioning]);
+  return /* @__PURE__ */ jsxs(SceneContext.Provider, { value: contextValue, children: [
+    /* @__PURE__ */ jsxs(Canvas, { shadows, children: [
+      config && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(SceneCamera, { config, transitionDuration, sceneKey: activeScene }),
+        /* @__PURE__ */ jsx(SceneControls, { type: controls, enabled: !isTransitioning, target: config.meta?.worldPosition }),
+        /* @__PURE__ */ jsx(ScenePostProcessing, { config: config.postProcessing })
+      ] }),
+      Array.from(scenes.entries()).map(([key, sceneConfig]) => /* @__PURE__ */ jsx("group", { position: sceneConfig.meta?.worldPosition || [0, 0, 0], children: /* @__PURE__ */ jsx(sceneConfig.Component, {}) }, key))
+    ] }),
+    children
+  ] });
+}
+
+// src/define-scenes.ts
+function defineScenes(config) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(config)) {
+    map.set(key, {
+      position: [0, 0, 5],
+      rotation: [0, 0, 0],
+      controls: "orbit",
+      camera: "perspective",
+      ...value
+    });
+  }
+  return map;
+}
+export {
+  SceneRouter,
+  defineScenes,
+  useScene,
+  useSceneTransition
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "r3f-scene-router",
+  "version": "0.1.0",
+  "description": "Declarative scene router for React Three Fiber — one persistent Canvas, many scenes with automatic camera transitions, controls, and post-processing",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "demo": "vite",
+    "demo:build": "vite build"
+  },
+  "keywords": [
+    "react-three-fiber",
+    "r3f",
+    "threejs",
+    "webgl",
+    "router",
+    "3d",
+    "scene-management",
+    "camera-transitions",
+    "post-processing"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/slaterhaus/r3f-scene-router"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "@react-three/fiber": ">=8.0.0",
+    "@react-three/drei": ">=9.0.0",
+    "@react-three/postprocessing": ">=2.0.0",
+    "three": ">=0.150.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "@react-three/fiber": "^8.16.0",
+    "@react-three/drei": "^9.100.0",
+    "@react-three/postprocessing": "^2.16.0",
+    "three": "^0.165.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@types/three": "^0.165.0"
+  }
+}