@toolproof-core/visualization 1.0.0

package/src/runtime/RuntimeController.tsx

@@ -0,0 +1,163 @@
+'use client';
+
+import RuntimeView, { type RuntimeCameraConfig } from './RuntimeView.js';
+import Portal, { type PortalInteractionPolicy } from '../primitives/Portal.js';
+import React, { useState, useRef, useEffect, useMemo, useCallback } from 'react';
+import * as THREE from 'three';
+import { OrbitControls } from '@react-three/drei';
+
+export type SpaceId = 'genesis' | 'strategy'; // ATTENTION: TYPE-SpaceIdentity
+
+export type PortalDescriptor = {
+    id: string;
+    from: SpaceId;
+    to: SpaceId;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: number;
+    visible: boolean;
+};
+
+export type RuntimeControllerStatus = {
+    activeSpace: SpaceId;
+    portal?: PortalDescriptor;
+    isTransitioning: boolean;
+};
+
+export type RuntimeControllerHandle = {
+    setActiveSpace: (space: SpaceId) => void;
+    transitionTo: (space: SpaceId, opts?: { via?: 'portal'; portalId?: string }) => void;
+    getStatus: () => RuntimeControllerStatus;
+    subscribeStatus: (listener: (status: RuntimeControllerStatus) => void) => () => void;
+};
+
+type OrbitControlsImpl = React.ElementRef<typeof OrbitControls>;
+
+export type RuntimeControllerRenderSpaceArgs = {
+    activeSpace: SpaceId;
+    orbitControlsRef: React.RefObject<OrbitControlsImpl | null>;
+    setPortal: (portal?: PortalDescriptor) => void;
+};
+
+export type RuntimeControllerProps = {
+    initialSpace: SpaceId;
+    cameraConfig: RuntimeCameraConfig;
+    renderSpace: (args: RuntimeControllerRenderSpaceArgs) => React.ReactNode;
+    background?: string;
+    /**
+     * Controls whether the user can activate/deactivate the runtime portal via gesture.
+     * Defaults to "toggle" to preserve existing behavior.
+     */
+    portalInteractionPolicy?: PortalInteractionPolicy;
+};
+
+export default React.forwardRef<RuntimeControllerHandle, RuntimeControllerProps>(function RuntimeController(props, ref) {
+    const [activeSpace, setActiveSpaceState] = useState<SpaceId>(props.initialSpace);
+    const [portalDescriptor, setPortalDescriptor] = useState<PortalDescriptor | undefined>(undefined);
+    const [isTransitioning, setIsTransitioning] = useState(false);
+    const [isPortalActive, setIsPortalActive] = useState(false);
+
+    const orbitControlsRef = useRef<OrbitControlsImpl | null>(null);
+    const cameraRef = useRef<THREE.Camera | null>(null);
+
+    const listenersRef = useRef(new Set<(status: RuntimeControllerStatus) => void>());
+
+    const setPortal = useCallback((portal?: PortalDescriptor) => {
+        setPortalDescriptor(portal);
+    }, []);
+
+    const status = useMemo<RuntimeControllerStatus>(() => {
+        return {
+            activeSpace,
+            // portal: portalDescriptor,
+            isTransitioning,
+        };
+    }, [activeSpace, isTransitioning, portalDescriptor]);
+
+    useEffect(() => {
+        for (const listener of listenersRef.current) {
+            listener(status);
+        }
+    }, [status]);
+
+    const setActiveSpace = useCallback((space: SpaceId) => {
+        setIsTransitioning(false);
+        setIsPortalActive(false);
+        setActiveSpaceState(space);
+    }, []);
+
+    const transitionTo = useCallback(
+        (space: SpaceId, opts?: { via?: 'portal'; portalId?: string }) => {
+            if (space === activeSpace) return;
+
+            if (opts?.via === 'portal') {
+                const canUsePortal =
+                    !!portalDescriptor?.visible &&
+                    portalDescriptor.from === activeSpace &&
+                    portalDescriptor.to === space &&
+                    (!opts.portalId || portalDescriptor.id === opts.portalId);
+
+                if (canUsePortal) {
+                    setIsTransitioning(true);
+                    setIsPortalActive(true);
+                    return;
+                }
+            }
+
+            setActiveSpace(space);
+        },
+        [activeSpace, portalDescriptor, setActiveSpace]
+    );
+
+    React.useImperativeHandle(
+        ref,
+        (): RuntimeControllerHandle => ({
+            setActiveSpace,
+            transitionTo,
+            getStatus: () => status,
+            subscribeStatus: (listener) => {
+                listenersRef.current.add(listener);
+                listener(status);
+                return () => {
+                    listenersRef.current.delete(listener);
+                };
+            },
+        }),
+        [setActiveSpace, status, transitionTo]
+    );
+
+    const showPortal = !!portalDescriptor?.visible && portalDescriptor.from === activeSpace;
+
+    return (
+        <RuntimeView cameraConfig={props.cameraConfig} orbitControlsRef={orbitControlsRef} cameraRef={cameraRef} background={props.background ?? 'skyblue'}>
+            {props.renderSpace({ activeSpace, orbitControlsRef, setPortal })}
+
+            {showPortal && portalDescriptor ? (
+                <group position={portalDescriptor.position} rotation={portalDescriptor.rotation} scale={portalDescriptor.scale}>
+                    <Portal
+                        isActive={isPortalActive}
+                        setIsActive={(active) => {
+                            setIsPortalActive(active);
+                            setIsTransitioning(active);
+                        }}
+                        interactionPolicy={props.portalInteractionPolicy ?? 'toggle'}
+                        orbitControlsRef={orbitControlsRef as unknown as React.RefObject<{ target: THREE.Vector3 } | null>}
+                        onTransitionComplete={(active) => {
+                            if (!active) {
+                                setIsTransitioning(false);
+                                setIsPortalActive(false);
+                                return;
+                            }
+
+                            // Transition finished: commit to the destination space.
+                            const destination = portalDescriptor.to;
+                            setIsTransitioning(false);
+                            setIsPortalActive(false);
+                            setActiveSpaceState(destination);
+                        }}
+                    />
+                </group>
+            ) : null}
+        </RuntimeView>
+    );
+});

package/src/runtime/RuntimeView.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import type React from 'react';
+import { Canvas } from '@react-three/fiber';
+import { OrbitControls } from '@react-three/drei';
+import { XR, createXRStore, useXR, type XRStore } from '@react-three/xr';
+import * as THREE from 'three';
+import { useEffect, useMemo, useRef } from 'react';
+
+export type RuntimeCameraConfig = {
+    position: [number, number, number];
+    target: [number, number, number];
+    fov: number;
+};
+
+type OrbitControlsImpl = React.ElementRef<typeof OrbitControls>;
+
+export const runtimeXrStore: XRStore = createXRStore();
+
+function RuntimeControls({
+    orbitControlsRef,
+    target,
+}: {
+    orbitControlsRef: React.RefObject<OrbitControlsImpl | null>;
+    target: [number, number, number];
+}) {
+    const session = useXR((state) => state.session);
+
+    return (
+        <OrbitControls
+            ref={orbitControlsRef}
+            target={target}
+            makeDefault
+            enableDamping
+            dampingFactor={0.05}
+            enabled={!session}
+        />
+    );
+}
+
+export default function RuntimeView(props: {
+    children: React.ReactNode;
+    cameraConfig: RuntimeCameraConfig;
+    orbitControlsRef?: React.RefObject<OrbitControlsImpl | null>;
+    cameraRef?: React.RefObject<THREE.Camera | null>;
+    background?: string;
+}) {
+    const { children, cameraConfig, background = 'skyblue' } = props;
+
+    const fallbackOrbitControlsRef = useRef<OrbitControlsImpl | null>(null);
+    const fallbackCameraRef = useRef<THREE.Camera | null>(null);
+
+    const orbitControlsRef = props.orbitControlsRef ?? fallbackOrbitControlsRef;
+    const cameraRef = props.cameraRef ?? fallbackCameraRef;
+
+    const initialCamera = useMemo(
+        () => ({ position: cameraConfig.position, fov: cameraConfig.fov }),
+        // Only used for initial mount; follow-up updates happen via effect.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        []
+    );
+
+    useEffect(() => {
+        const camera = cameraRef.current;
+        const controls = orbitControlsRef.current;
+        if (!camera || !controls) return;
+
+        camera.position.set(...cameraConfig.position);
+        if ('fov' in camera && typeof (camera as THREE.PerspectiveCamera).fov === 'number') {
+            (camera as THREE.PerspectiveCamera).fov = cameraConfig.fov;
+            (camera as THREE.PerspectiveCamera).updateProjectionMatrix();
+        }
+
+        controls.target.set(...cameraConfig.target);
+        controls.update();
+    }, [cameraConfig, cameraRef, orbitControlsRef]);
+
+    return (
+        <Canvas
+            style={{ width: '100%', height: '100%' }}
+            camera={initialCamera}
+            onCreated={({ camera, scene }) => {
+                cameraRef.current = camera;
+                scene.background = new THREE.Color(background);
+            }}
+        >
+            <XR store={runtimeXrStore}>
+                <RuntimeControls orbitControlsRef={orbitControlsRef} target={cameraConfig.target} />
+                {children}
+            </XR>
+        </Canvas>
+    );
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "jsx": "react-jsx",
+  },
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/_lib/types.ts","./src/primitives/portal.tsx","./src/primitives/ringofmeshes.tsx","./src/primitives/spokeofmeshes.tsx","./src/runtime/runtimecontroller.tsx","./src/runtime/runtimeview.tsx"],"version":"5.9.3"}