@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/external/ExternalCanvas.js

@@ -0,0 +1,177 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { _roots, advance, createRoot, extend } from '@react-three/fiber';
+import { StrictMode, useEffect, useEffectEvent, useRef } from 'react';
+import * as THREE from 'three';
+import { Camera, WebGLRenderer } from 'three';
+import { createLogger } from '../utils/logging';
+import { setExternalCameraProjection } from './external-camera';
+import { externalEvents } from './external-events';
+const logger = createLogger('external');
+/**
+ * `<Canvas>`'s stand-in for a host that already owns the canvas: everything the Canvas component
+ * does — boot an R3F root, configure the renderer, the events, the size — minus the one thing it
+ * cannot share, creating the canvas element. It knows nothing of the scene: `children` render into
+ * the root verbatim, so `Renderer` composes one tree and only the mount differs.
+ *
+ * The bootstrap is imperative because the host's contract is: there is no React tree to mount into
+ * until a context exists. R3F's `<Canvas>` cannot serve here — it creates and owns its own canvas
+ * element inside a wrapper it renders, and has no way to adopt a foreign one — so this takes R3F's
+ * own escape hatch for exactly that, `createRoot(canvas)`, which is all `<Canvas>` wraps anyway.
+ * It is configured once per context, while the tree re-renders through props like any other.
+ *
+ * The camera half is the mount's as well, because the host owns it: one bare camera carries
+ * whatever matrix the host handed the frame hook, decomposed into a rigid view and a projection so
+ * that everything reading a camera's transform — culling, raycasts, lighting — works unchanged.
+ * There is no viewbox fit, no controls and no camera commands; the tree above simply mounts none
+ * of them.
+ *
+ * The demand loop inverts. R3F's own `invalidate` is a no-op under `frameloop: 'never'`, so the
+ * store's copy is replaced with the host's `requestFrame` — and every host frame redraws in full,
+ * as a shared canvas requires, starting from `resetState()` so three's GL-state tracking never
+ * trusts what the host's own drawing left behind.
+ * @param props - The host's hooks, and the tree to render into the root.
+ * @returns Nothing; the tree renders on the host's canvas, not in this one.
+ */
+export function ExternalCanvas(props) {
+    const { gl, requestFrame, onFrame, children } = props;
+    // A ref rather than state: nothing renders from the root — the tree renders *into* it — and the
+    // forwarding effect always runs after this one within a commit, so it never reads it stale.
+    const mountedRef = useRef(undefined);
+    // Effect events, so the host handing over a fresh function identity neither re-bootstraps the
+    // root nor goes stale: the bootstrap captures these two, and they read the latest props.
+    const askFrame = useEffectEvent(() => requestFrame());
+    const subscribeFrames = useEffectEvent((draw) => onFrame(draw));
+    useEffect(() => {
+        const external = mountExternal(gl, askFrame, subscribeFrames);
+        mountedRef.current = external;
+        return () => {
+            mountedRef.current = undefined;
+            external?.dispose();
+        };
+    }, [gl]);
+    // The tree flows into the foreign root exactly as it would into a Canvas: every children change
+    // re-renders it, and only a context change re-bootstraps — `gl` is a dependency here for exactly
+    // that case, so a fresh root receives the tree the moment it exists.
+    useEffect(() => {
+        mountedRef.current?.render(_jsx(StrictMode, { children: children }));
+    }, [gl, children]);
+    return null;
+}
+/**
+ * Boots an R3F root on the host's canvas and wires it to the host's frame loop.
+ * @param context - The host's WebGL context.
+ * @param requestFrame - Asks the host for a frame.
+ * @param onFrame - Subscribes the per-frame draw to the host.
+ * @returns The root and its teardown, or `undefined` when the context has no usable canvas.
+ */
+function mountExternal(context, requestFrame, onFrame) {
+    const canvas = context.canvas;
+    if (!(canvas instanceof HTMLCanvasElement)) {
+        logger.warn('external mode needs a context bound to an HTMLCanvasElement');
+        return undefined;
+    }
+    // `<Canvas>` extends R3F's element catalog with the whole THREE namespace itself; a manual root
+    // has to do the same. Idempotent, and the namespace is a module the renderer already ships. The
+    // cast steps past the catalog's constructors-only typing — the namespace carries plain values
+    // too, which `extend` skips at runtime, exactly as the Canvas path relies on.
+    extend(THREE);
+    // Deliberately a bare camera: three's frustum cameras derive their projection, and this one's
+    // arrives whole from the host each frame. Marked manual so R3F's resize handling leaves it
+    // alone; both auto-updates are off because the decomposition writes every matrix by hand.
+    const camera = new Camera();
+    camera.matrixAutoUpdate = false;
+    camera.matrixWorldAutoUpdate = false;
+    camera.manual = true;
+    // Constructed bare on purpose: anything the renderer would opine on is left unset.
+    const glRenderer = new WebGLRenderer({ canvas, context });
+    // Never clear: the host's own layers are already on the canvas when this renderer draws.
+    glRenderer.autoClear = false;
+    // The canvas is the host's, twice over. Three would write the css style along with every resize
+    // unless told otherwise each time; and R3F's unmount forces a context loss on the renderer it
+    // tears down, which on a shared context would take the host's own drawing with it.
+    const applySize = glRenderer.setSize.bind(glRenderer);
+    glRenderer.setSize = (width, height) => applySize(width, height, false);
+    glRenderer.forceContextLoss = () => undefined;
+    const measure = () => {
+        const rect = canvas.getBoundingClientRect();
+        return { width: rect.width, height: rect.height, top: rect.top, left: rect.left };
+    };
+    const root = createRoot(canvas);
+    let disposed = false;
+    let configured = false;
+    let pending;
+    let unsubscribeFrame;
+    let observer;
+    void root
+        .configure({
+        gl: glRenderer,
+        // R3F force-writes ACES filmic tone mapping onto a fresh renderer unless `flat` is set, which
+        // is the one value landing on three's own default, `NoToneMapping`. This renderer does not
+        // tone map: `Lighting` keeps the rig's light sum in range by construction, rather than
+        // compressing an unbounded one back into range afterward.
+        flat: true,
+        // The cast widens past R3F's frustum-camera union; `manual` above is what keeps R3F's own
+        // camera handling off it.
+        camera: camera,
+        frameloop: 'never',
+        events: externalEvents,
+        size: measure(),
+        dpr: window.devicePixelRatio,
+    })
+        .then(() => {
+        if (disposed)
+            return;
+        const store = _roots.get(canvas)?.store;
+        if (!store)
+            return;
+        // R3F's invalidate no-ops under `frameloop: 'never'`; the host owns the frames, so demand
+        // becomes a repaint request. Replaced after configure, which is what wrote the original.
+        store.setState({
+            invalidate: () => {
+                if (!disposed)
+                    requestFrame();
+            },
+        });
+        store.getState().events.connect?.(canvas);
+        unsubscribeFrame = onFrame((projectionMatrix) => {
+            if (disposed)
+                return;
+            setExternalCameraProjection(camera, projectionMatrix);
+            // Three tracks GL state it did not set; sharing a context means resetting that tracking
+            // at the start of every frame, or the host's own state reads as three's.
+            glRenderer.resetState();
+            advance(performance.now(), true, store.getState());
+        });
+        // The host resizes its own canvas; the root only has to notice. Watching the element beats a
+        // host-specific resize event, and a dpr change reaches the same handler through the resize
+        // the host performs for it. Feature-detected for the oldest WebViews the SDK still runs in —
+        // without the observer the plan still draws, at the size it mounted at.
+        if (typeof ResizeObserver === 'function') {
+            observer = new ResizeObserver(() => {
+                if (disposed)
+                    return;
+                const next = measure();
+                store.getState().setSize(next.width, next.height, next.top, next.left);
+                store.getState().setDpr(window.devicePixelRatio);
+            });
+            observer.observe(canvas);
+        }
+        configured = true;
+        if (pending !== undefined)
+            root.render(pending);
+        requestFrame();
+    });
+    return {
+        render(node) {
+            pending = node;
+            if (configured)
+                root.render(node);
+        },
+        dispose() {
+            disposed = true;
+            observer?.disconnect();
+            unsubscribeFrame?.();
+            root.unmount();
+        },
+    };
+}

package/dist/external/external-camera.d.ts

@@ -0,0 +1,18 @@
+import { type Camera } from 'three';
+/**
+ * Decomposes the host's combined world-to-clip matrix into a rigid view matrix and a projection
+ * matrix, publishing all four matrices (and their inverses) on the camera.
+ *
+ * Ported from the imperative renderer's `ExternalCameraSystem`. The split is not unique — many
+ * (P′, V′) pairs multiply to the same M — but the *rigid* split is the one three's `Camera` class
+ * assumes for `getWorldDirection`, frustum culling, raycasting and the lighting that reads the
+ * camera's world matrix. Any extra scale or skew in M (mercator-unit conversion, say) ends up
+ * absorbed into P, where it breaks none of those — a *reflection* being the exception, which is why
+ * the host's world is mirrored into three's before any of this runs.
+ * @param camera - The external camera to publish onto; `matrixAutoUpdate` and
+ *   `matrixWorldAutoUpdate` must be off, since everything here is written by hand.
+ * @param mainMatrix - The combined matrix mapping world space directly to clip space, sixteen
+ *   elements column-major.
+ */
+export declare function setExternalCameraProjection(camera: Camera, mainMatrix: ArrayLike<number>): void;
+//# sourceMappingURL=external-camera.d.ts.map

package/dist/external/external-camera.js

@@ -0,0 +1,103 @@
+import { Matrix3, Matrix4, Vector3 } from 'three';
+import { HANDEDNESS_FLIP } from '../space/Space';
+/**
+ * Decomposes the host's combined world-to-clip matrix into a rigid view matrix and a projection
+ * matrix, publishing all four matrices (and their inverses) on the camera.
+ *
+ * Ported from the imperative renderer's `ExternalCameraSystem`. The split is not unique — many
+ * (P′, V′) pairs multiply to the same M — but the *rigid* split is the one three's `Camera` class
+ * assumes for `getWorldDirection`, frustum culling, raycasting and the lighting that reads the
+ * camera's world matrix. Any extra scale or skew in M (mercator-unit conversion, say) ends up
+ * absorbed into P, where it breaks none of those — a *reflection* being the exception, which is why
+ * the host's world is mirrored into three's before any of this runs.
+ * @param camera - The external camera to publish onto; `matrixAutoUpdate` and
+ *   `matrixWorldAutoUpdate` must be off, since everything here is written by hand.
+ * @param mainMatrix - The combined matrix mapping world space directly to clip space, sixteen
+ *   elements column-major.
+ */
+export function setExternalCameraProjection(camera, mainMatrix) {
+    // The host's matrix reads the host's world; the space mirrors that world into three's, so undo
+    // the mirror here. The two cancel: the plan lands exactly where the host put it, and what is left
+    // is a plan → world matrix that reverses orientation, which is the whole point — see
+    // {@link HANDEDNESS_FLIP}.
+    const M = _main.fromArray(mainMatrix).multiply(HANDEDNESS_FLIP);
+    const e = M.elements; // column-major storage: M[row, col] = e[row + 4 * col]
+    // Step 1: camera world position c.
+    //
+    // A standard perspective projection P has its fourth column equal to (0, 0, ±f, 0), so
+    // P · [0; 0; 0; 1] is zero in rows 0, 1, and 3. The view matrix V maps the camera position to
+    // view-space origin: V · [c; 1] = [0; 0; 0; 1]. Composing these:
+    //
+    //     M · [c; 1] = P · V · [c; 1] = P · [0; 0; 0; 1] = (0, 0, k, 0)
+    //
+    // so rows 0, 1, and 3 of M dotted with [c; 1] all equal zero. That is a 3×3 linear system for
+    // the three components of c, independent of NDC z conventions (standard OpenGL vs. reverse-z),
+    // so it works for both maplibre and a vanilla GL setup.
+    _system.set(e[0], e[4], e[8], e[1], e[5], e[9], e[3], e[7], e[11]);
+    _position.set(-e[12], -e[13], -e[15]).applyMatrix3(_system.invert());
+    // Step 2: view direction in world space.
+    //
+    // Unproject two world-space points along the central view ray and take their difference. The
+    // clip-space z boundaries (±1) are used rather than an interior NDC z because maplibre's
+    // projection has an infinite far plane in a reverse-z arrangement: an interior z (0 in
+    // particular) unprojects to a homogeneous direction at infinity and comes back as NaN after the
+    // w-divide. z = ±1 always produces finite points, so the subtraction is well-defined.
+    //
+    // Which of the two is the near plane depends on the projection's z convention — reverse-z under
+    // maplibre, standard under vanilla GL — so it is settled by distance to the eye recovered above:
+    // the near point is the closer one, and the view looks from it toward the other. (The imperative
+    // renderer hardcoded maplibre's ordering; measuring is what makes both conventions work.)
+    _mainInverse.copy(M).invert();
+    _near.set(0, 0, 1).applyMatrix4(_mainInverse);
+    _far.set(0, 0, -1).applyMatrix4(_mainInverse);
+    const nearZ = _near.distanceToSquared(_position) <= _far.distanceToSquared(_position) ? 1 : -1;
+    if (nearZ === 1) {
+        _direction.copy(_far).sub(_near).normalize();
+    }
+    else {
+        _direction.copy(_near).sub(_far).normalize();
+    }
+    // Step 3: the camera's up axis, measured rather than chosen, and a rigid view matrix from it.
+    //
+    // Any up not parallel to the view direction gives a valid (P′, V′) pair for *drawing*, because P
+    // is recomputed from M · matrixWorld at the end and absorbs whatever roll V′ was given. The axis
+    // is also *read*, though: `Lighting` takes the plan's heading from the camera's up axis, so a
+    // chosen one aims the key light at an angle the host never had — a fixed world +z aimed it from
+    // the far side of the plan at every bearing, and every face turned toward the camera lost its
+    // direct light.
+    //
+    // Two points at one clip x and one clip z, one at the top of the screen and one at the bottom,
+    // differ by a vector along the camera's up axis alone: a constant clip z is a constant view-space
+    // z, so the forward components cancel and the difference is (0, Δy, 0) in view space. Clip y
+    // grows upward under every projection, maplibre's reverse-z included, so this reads none of the
+    // host's own conventions — and unlike a chosen axis it has no degenerate view to fall back from,
+    // since the axis it recovers is perpendicular to the view direction by construction.
+    //
+    // Unprojected at `nearZ`, the near plane's own clip z: a point there is finite under either z
+    // convention, which an interior z is not.
+    _screenTop.set(0, 1, nearZ).applyMatrix4(_mainInverse);
+    _screenBottom.set(0, -1, nearZ).applyMatrix4(_mainInverse);
+    _up.copy(_screenTop).sub(_screenBottom).normalize();
+    _target.copy(_position).add(_direction);
+    camera.matrixWorld.lookAt(_position, _target, _up);
+    camera.matrixWorld.setPosition(_position);
+    camera.matrixWorldInverse.copy(camera.matrixWorld).invert();
+    // Step 4: derive projection so that P · V = M exactly.
+    //
+    // P = M · matrixWorld, because matrixWorld = V⁻¹ and therefore P · V = (M · V⁻¹) · V = M. Any
+    // scale or skew that did not fit into the rigid V lives in P.
+    camera.projectionMatrix.multiplyMatrices(M, camera.matrixWorld);
+    camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
+}
+// Scratch, reused across calls so a per-frame update allocates nothing.
+const _main = new Matrix4();
+const _mainInverse = new Matrix4();
+const _system = new Matrix3();
+const _position = new Vector3();
+const _near = new Vector3();
+const _far = new Vector3();
+const _direction = new Vector3();
+const _screenTop = new Vector3();
+const _screenBottom = new Vector3();
+const _target = new Vector3();
+const _up = new Vector3();

package/dist/external/external-events.d.ts

@@ -0,0 +1,14 @@
+import { type EventManager, type RootStore } from '@react-three/fiber';
+/**
+ * R3F's DOM event manager, aiming its rays through the hosted camera.
+ *
+ * The default manager computes its ray with three's `setFromCamera`, which refuses a camera that is
+ * neither perspective nor orthographic — and the external camera is deliberately neither, one folded
+ * matrix with no transform of its own. Only the computation changes: hit testing, hover tracking,
+ * capture and the missed-click path all stay R3F's, so picking under a host behaves exactly as it
+ * does under the renderer's own canvas.
+ * @param store - The root the manager serves.
+ * @returns The event manager.
+ */
+export declare function externalEvents(store: RootStore): EventManager<HTMLElement>;
+//# sourceMappingURL=external-events.d.ts.map

package/dist/external/external-events.js

@@ -0,0 +1,33 @@
+import { events as createDomEvents } from '@react-three/fiber';
+import { castRay } from '../space/Space';
+/**
+ * R3F's DOM event manager, aiming its rays through the hosted camera.
+ *
+ * The default manager computes its ray with three's `setFromCamera`, which refuses a camera that is
+ * neither perspective nor orthographic — and the external camera is deliberately neither, one folded
+ * matrix with no transform of its own. Only the computation changes: hit testing, hover tracking,
+ * capture and the missed-click path all stay R3F's, so picking under a host behaves exactly as it
+ * does under the renderer's own canvas.
+ * @param store - The root the manager serves.
+ * @returns The event manager.
+ */
+export function externalEvents(store) {
+    const manager = createDomEvents(store);
+    return {
+        ...manager,
+        // The canvas is the host's and carries the host's own pointer handling; listening one element
+        // up leaves it alone, while `offsetX` stays canvas-relative — the events still target the
+        // canvas, which sits alone in its container.
+        connect(target) {
+            manager.connect?.(target.parentElement ?? target);
+        },
+        compute(event, state) {
+            state.pointer.set((event.offsetX / state.size.width) * 2 - 1, -(event.offsetY / state.size.height) * 2 + 1);
+            // R3F's pointer is a bare Vector2; the set above is what put it in NDC.
+            castRay(state.raycaster, state.pointer, state.camera);
+            // Screen-space raycasts — a route line answering at its drawn width — read the camera off the
+            // raycaster; `setFromCamera` writes it and the general-camera path must too.
+            state.raycaster.camera = state.camera;
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { type CameraAPI, type CameraAxes, type CameraState, type ControlsConfig, type InertiaConfig, type PanConfig, type RollConfig, type TransitionOptions, useCameraAPI, useCameraGesture, useCameraMoveEnd, useCameraState, type ZoomConfig, type ZoomToOptions, } from './controls';
+export { prepareDebug } from './debug/debug-chunk';
+export { useDebugPanel } from './debug/debug-context';
+export { type LightingProps, type ShadowProps } from './objects/lighting';
+export * from './Renderer';
+export { type CameraProps, type SmoothTime } from './space/Camera';
+export { type CanvasPoint, type CanvasPointLike, type PlanPoint, type PlanPointLike, } from './space/Space';
+export { useViewport, type ViewportAPI } from './space/viewport';
+export * from './types/defs';
+export * from './types/events';
+export * from './types/guards';
+export { update } from './update';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,14 @@
+// The camera's public surface: commands, a state reader, and the two movement events — the user's
+// own hand on the camera, and any movement coming to rest. Deliberately not `useControlsEffect` or
+// the controls themselves — those hand out `camera-controls`, which is this renderer's internals.
+export { useCameraAPI, useCameraGesture, useCameraMoveEnd, useCameraState, } from './controls';
+// The debug chunk's preload, for an external host that must create its context instrumented.
+export { prepareDebug } from './debug/debug-chunk';
+// Publishing a host's own values into the debug panel.
+export { useDebugPanel } from './debug/debug-context';
+export * from './Renderer';
+export { useViewport } from './space/viewport';
+export * from './types/defs';
+export * from './types/events';
+export * from './types/guards';
+export { update } from './update';

package/dist/objects/Background.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from 'react';
+import { type ColorInput } from '../types/defs';
+/** Props for {@link Background}. */
+export interface BackgroundProps {
+    /** The background color. */
+    color: ColorInput;
+}
+/**
+ * The scene's background: a screen-space quad drawn below every layer, replacing what a clear
+ * color would paint — and unlike one, dimmed with the venue. The root `Layer` renders it inside
+ * its own group, under the root layer's dim provider, so the dim reaches this material exactly as
+ * it reaches a layer's.
+ *
+ * **Screen-space in the vertex shader**, as the imperative renderer drew it: projection is
+ * replaced with the quad's own xy in clip space at the far plane, so it covers the canvas edge to
+ * edge under any camera — fit, zoom, roll, pitch — and no matrix above it is ever read.
+ *
+ * It draws through the same {@link ColorMaterial} as the layers, with one addition through the
+ * material's pre-dim hook: a quad has no batch prologue, so the per-instance dim uniform the
+ * unmodified dim patch looks for is declared here as a constant pinned to "inherit" — every
+ * fragment defers to the layer amount, which is the point.
+ *
+ * **Draw order**: `renderOrder` 0 puts it level with the first layer group, and the tie falls to
+ * `material.id` — this material is created as the root layer mounts, before the scheduler admits
+ * any leaf, so it draws first. That ordering is load-bearing: flat content writes no depth, so
+ * anything drawn after the quad simply paints over it.
+ * @param props - The color.
+ * @returns The quad.
+ */
+export declare function Background(props: BackgroundProps): ReactNode;
+//# sourceMappingURL=Background.d.ts.map

package/dist/objects/Background.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { declareBeforeMain } from '../core/shader-source';
+import { ColorMaterial } from './materials/ColorMaterial';
+import { DIM_INHERIT, DIM_UNIFORM } from './materials/effects/color-dim';
+/**
+ * The scene's background: a screen-space quad drawn below every layer, replacing what a clear
+ * color would paint — and unlike one, dimmed with the venue. The root `Layer` renders it inside
+ * its own group, under the root layer's dim provider, so the dim reaches this material exactly as
+ * it reaches a layer's.
+ *
+ * **Screen-space in the vertex shader**, as the imperative renderer drew it: projection is
+ * replaced with the quad's own xy in clip space at the far plane, so it covers the canvas edge to
+ * edge under any camera — fit, zoom, roll, pitch — and no matrix above it is ever read.
+ *
+ * It draws through the same {@link ColorMaterial} as the layers, with one addition through the
+ * material's pre-dim hook: a quad has no batch prologue, so the per-instance dim uniform the
+ * unmodified dim patch looks for is declared here as a constant pinned to "inherit" — every
+ * fragment defers to the layer amount, which is the point.
+ *
+ * **Draw order**: `renderOrder` 0 puts it level with the first layer group, and the tie falls to
+ * `material.id` — this material is created as the root layer mounts, before the scheduler admits
+ * any leaf, so it draws first. That ordering is load-bearing: flat content writes no depth, so
+ * anything drawn after the quad simply paints over it.
+ * @param props - The color.
+ * @returns The quad.
+ */
+export function Background(props) {
+    // One handler for the material's life, per `ColorMaterial`'s contract for its pre-dim hook.
+    const [onBeforeCompile] = useState(() => (parameters) => {
+        parameters.vertexShader = parameters.vertexShader.replace('#include <project_vertex>', 
+        /* glsl */ `gl_Position = vec4(transformed.xy, 1.0, 1.0);`);
+        parameters.fragmentShader = declareBeforeMain(parameters.fragmentShader, 
+        /* glsl */ `const float ${DIM_UNIFORM} = ${DIM_INHERIT}.0;`);
+    });
+    return (_jsxs("mesh", { name: "background", renderOrder: 0, frustumCulled: false, children: [_jsx("planeGeometry", { args: [2, 2] }), _jsx(ColorMaterial, { color: props.color, onBeforeCompile: onBeforeCompile })] }));
+}