@expofp/renderer 3.2.4 → 3.27.0

package/dist/core/text/glyph-packing.d.ts

@@ -0,0 +1,17 @@
+import { type GlyphsGeometry, type TextRenderInfo } from 'troika-three-text';
+import { type TextExt } from './Text';
+/**
+ * Rewrites a batch's glyph attributes from its members' render info.
+ *
+ * Two orders meet here, which is the whole point of the pass: glyph runs are appended in *paint*
+ * order, since draw order is simply the order runs appear in the batched attributes, while the
+ * member index each run carries is the member’s stable *id*, which is the row it reads its matrix
+ * and uniforms from.
+ * @param geometry - The batch's glyph geometry, whose attributes are replaced.
+ * @param ordered - The ids to draw, in paint order.
+ * @param textAt - The member holding an id, or `undefined` when it holds none.
+ * @returns The render info the batch should adopt as its own — any member's will do, since a batch
+ *   shares one SDF atlas — or `undefined` when no member has synced.
+ */
+export declare function packGlyphs(geometry: GlyphsGeometry, ordered: readonly number[], textAt: (memberId: number) => TextExt | undefined): TextRenderInfo | undefined;
+//# sourceMappingURL=glyph-packing.d.ts.map

package/dist/core/text/glyph-packing.js

@@ -0,0 +1,61 @@
+import { DynamicDrawUsage } from 'three';
+import { resizeTypedArray } from '../typed-array';
+import { MEMBER_INDEX_ATTRIBUTE } from './batched-text-material';
+/**
+ * Rewrites a batch's glyph attributes from its members' render info.
+ *
+ * Two orders meet here, which is the whole point of the pass: glyph runs are appended in *paint*
+ * order, since draw order is simply the order runs appear in the batched attributes, while the
+ * member index each run carries is the member’s stable *id*, which is the row it reads its matrix
+ * and uniforms from.
+ * @param geometry - The batch's glyph geometry, whose attributes are replaced.
+ * @param ordered - The ids to draw, in paint order.
+ * @param textAt - The member holding an id, or `undefined` when it holds none.
+ * @returns The render info the batch should adopt as its own — any member's will do, since a batch
+ *   shares one SDF atlas — or `undefined` when no member has synced.
+ */
+export function packGlyphs(geometry, ordered, textAt) {
+    const attributes = geometry.attributes;
+    let memberIndexes = attributes[MEMBER_INDEX_ATTRIBUTE]?.array ?? new Uint16Array(0);
+    let glyphIndexes = attributes[GLYPH_INDEX_ATTRIBUTE]?.array ?? new Float32Array(0);
+    let glyphBounds = attributes[GLYPH_BOUNDS_ATTRIBUTE]?.array ?? new Float32Array(0);
+    // Initial pass to collect total glyph count and resize the arrays if needed.
+    let totalGlyphCount = 0;
+    // The inherited `Text` code reads `textRenderInfo` for whole-batch state (the SDF atlas, its glyph
+    // size and exponent); any member's will do.
+    let batchRenderInfo;
+    for (const memberId of ordered) {
+        const renderInfo = textAt(memberId)?.textRenderInfo;
+        if (!renderInfo)
+            continue;
+        totalGlyphCount += renderInfo.glyphAtlasIndices.length;
+        batchRenderInfo = renderInfo;
+    }
+    if (totalGlyphCount !== memberIndexes.length) {
+        memberIndexes = resizeTypedArray(memberIndexes, totalGlyphCount);
+        glyphIndexes = resizeTypedArray(glyphIndexes, totalGlyphCount);
+        glyphBounds = resizeTypedArray(glyphBounds, totalGlyphCount * 4);
+    }
+    // Populate batch arrays.
+    let glyphIndex = 0;
+    for (const memberId of ordered) {
+        const renderInfo = textAt(memberId)?.textRenderInfo;
+        if (!renderInfo)
+            continue;
+        const glyphCount = renderInfo.glyphAtlasIndices.length;
+        memberIndexes.fill(memberId, glyphIndex, glyphIndex + glyphCount);
+        glyphIndexes.set(renderInfo.glyphAtlasIndices, glyphIndex);
+        glyphBounds.set(renderInfo.glyphBounds, glyphIndex * 4);
+        glyphIndex += glyphCount;
+    }
+    // Update the geometry attributes.
+    geometry.updateAttributeData(MEMBER_INDEX_ATTRIBUTE, memberIndexes, 1);
+    geometry.getAttribute(MEMBER_INDEX_ATTRIBUTE).setUsage(DynamicDrawUsage);
+    geometry.updateAttributeData(GLYPH_INDEX_ATTRIBUTE, glyphIndexes, 1);
+    geometry.updateAttributeData(GLYPH_BOUNDS_ATTRIBUTE, glyphBounds, 4);
+    return batchRenderInfo;
+}
+/** One SDF atlas index per glyph. */
+const GLYPH_INDEX_ATTRIBUTE = 'aTroikaGlyphIndex';
+/** Four floats per glyph, bounding the quad it is drawn on. */
+const GLYPH_BOUNDS_ATTRIBUTE = 'aTroikaGlyphBounds';

package/dist/core/typed-array.d.ts

@@ -0,0 +1,16 @@
+import { type TypedArray } from 'three';
+/**
+ * Copies a typed array into a fresh one of a different length, keeping as much of the contents as
+ * fits: growing zero-fills the tail, shrinking drops it.
+ *
+ * The element type is taken from the source's own constructor rather than a parameter, so a caller
+ * resizing a `Uint16Array` of member indexes and one resizing a `Float32Array` of glyph bounds share
+ * the same call. Always a new array — an in-place `ArrayBuffer.resize` would not do here, because
+ * both callers hand the result to something that captured the old buffer (three's `BufferAttribute`,
+ * or a `DataTexture`'s image) and must see a distinct one to notice the change.
+ * @param source - The array to copy.
+ * @param length - The new array's length, in elements.
+ * @returns The resized copy.
+ */
+export declare function resizeTypedArray<T extends TypedArray>(source: T, length: number): T;
+//# sourceMappingURL=typed-array.d.ts.map

package/dist/core/typed-array.js

@@ -0,0 +1,20 @@
+/**
+ * Copies a typed array into a fresh one of a different length, keeping as much of the contents as
+ * fits: growing zero-fills the tail, shrinking drops it.
+ *
+ * The element type is taken from the source's own constructor rather than a parameter, so a caller
+ * resizing a `Uint16Array` of member indexes and one resizing a `Float32Array` of glyph bounds share
+ * the same call. Always a new array — an in-place `ArrayBuffer.resize` would not do here, because
+ * both callers hand the result to something that captured the old buffer (three's `BufferAttribute`,
+ * or a `DataTexture`'s image) and must see a distinct one to notice the change.
+ * @param source - The array to copy.
+ * @param length - The new array's length, in elements.
+ * @returns The resized copy.
+ */
+export function resizeTypedArray(source, length) {
+    const constructor = source.constructor;
+    const resized = new constructor(length);
+    // `subarray` clamps to the source's own length, so this is also the growing case.
+    resized.set(source.subarray(0, length));
+    return resized;
+}

package/dist/debug/components/DebugPanelProvider.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+/** Props for {@link DebugPanelProvider}. */
+export interface DebugPanelProviderProps {
+    /** The scene to publish from. */
+    children: ReactNode;
+}
+/**
+ * Owns the debug panel's entries and the write API that fills them.
+ *
+ * Deliberately *inside* the `<Canvas>`. R3F re-runs its configuration on every render of the canvas
+ * element, and that path replaces the `size` object in its store even when the dimensions have not
+ * changed — so state held above the canvas and written once per frame, as a camera publishing its
+ * position is, hands every `useThree(state => state.size)` subscriber a new object every frame. Held
+ * here, a push re-renders this component and the panel below it and nothing else: `children` arrives
+ * as an unchanged element, so React skips the scene entirely.
+ * @param props - The scene to publish from.
+ * @returns The scene, under the panel's write API, with the panel beside it.
+ */
+export declare function DebugPanelProvider(props: DebugPanelProviderProps): ReactNode;
+//# sourceMappingURL=DebugPanelProvider.d.ts.map

package/dist/debug/components/DebugPanelProvider.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { DebugPanelContext } from '../debug-context';
+import { Panel } from './Panel';
+/**
+ * Owns the debug panel's entries and the write API that fills them.
+ *
+ * Deliberately *inside* the `<Canvas>`. R3F re-runs its configuration on every render of the canvas
+ * element, and that path replaces the `size` object in its store even when the dimensions have not
+ * changed — so state held above the canvas and written once per frame, as a camera publishing its
+ * position is, hands every `useThree(state => state.size)` subscriber a new object every frame. Held
+ * here, a push re-renders this component and the panel below it and nothing else: `children` arrives
+ * as an unchanged element, so React skips the scene entirely.
+ * @param props - The scene to publish from.
+ * @returns The scene, under the panel's write API, with the panel beside it.
+ */
+export function DebugPanelProvider(props) {
+    const { children } = props;
+    const [entries, setEntries] = useState({});
+    // Not memoized by hand: the React Compiler keeps this object stable, so DebugPanelContext
+    // consumers don't re-render when `entries` changes. Both updaters take the functional form, so
+    // nothing here closes over the entries themselves.
+    const panel = {
+        set(key, value) {
+            setEntries((prev) => key in prev && Object.is(prev[key], value) ? prev : { ...prev, [key]: value });
+        },
+        remove(key) {
+            setEntries((prev) => {
+                if (!(key in prev))
+                    return prev;
+                const next = { ...prev };
+                delete next[key];
+                return next;
+            });
+        },
+    };
+    return (_jsxs(DebugPanelContext, { value: panel, children: [children, _jsx(Panel, { corner: "right", label: "Debug", value: entries })] }));
+}

package/dist/debug/components/DebugTools.d.ts

@@ -0,0 +1,22 @@
+import 'webgl-memory';
+import { type ReactNode } from 'react';
+/** Props for {@link DebugTools}. */
+export interface DebugToolsProps {
+    /** The scene to instrument. */
+    children?: ReactNode;
+}
+/**
+ * The debug overlay, canvas-free — the heavy, lazily-loaded chunk. Wraps the scene in the debug
+ * GUI (shared through context so scene components can add folders) and the debug-panel write API
+ * (so scene components can publish values via `useDebugPanel`), plus the frame-stats, GPU-memory,
+ * and combined debug-values panels. All of it attaches to the document imperatively, outside the
+ * R3F reconciler, which is what lets the same component serve both mounts: inside the renderer's
+ * own `<Canvas>` and inside an external host's root alike.
+ *
+ * lil-gui, stats-gl and webgl-memory are reachable only through here, so this module is loaded
+ * exclusively via the debug entry's dynamic import and never lands in the main bundle.
+ * @param props - The scene to instrument.
+ * @returns The scene wrapped in the debug overlay.
+ */
+export declare function DebugTools(props: DebugToolsProps): ReactNode;
+//# sourceMappingURL=DebugTools.d.ts.map

package/dist/debug/components/DebugTools.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Patches `HTMLCanvasElement.getContext` during chunk eval, so any context created after this
+// chunk loads is born instrumented. The internal mount guarantees the ordering by suspending its
+// Canvas behind this chunk (see `CanvasWithDebug`); an external host has to arrange it itself by
+// awaiting `prepareDebug()` before creating its map — its context predates this code otherwise,
+// and the memory panel stays empty.
+import 'webgl-memory';
+import { DebugPanelProvider } from './DebugPanelProvider';
+import { Gui } from './Gui';
+import { MemoryInfo } from './MemoryInfo';
+import { Stats } from './Stats';
+/**
+ * The debug overlay, canvas-free — the heavy, lazily-loaded chunk. Wraps the scene in the debug
+ * GUI (shared through context so scene components can add folders) and the debug-panel write API
+ * (so scene components can publish values via `useDebugPanel`), plus the frame-stats, GPU-memory,
+ * and combined debug-values panels. All of it attaches to the document imperatively, outside the
+ * R3F reconciler, which is what lets the same component serve both mounts: inside the renderer's
+ * own `<Canvas>` and inside an external host's root alike.
+ *
+ * lil-gui, stats-gl and webgl-memory are reachable only through here, so this module is loaded
+ * exclusively via the debug entry's dynamic import and never lands in the main bundle.
+ * @param props - The scene to instrument.
+ * @returns The scene wrapped in the debug overlay.
+ */
+export function DebugTools(props) {
+    const { children } = props;
+    return (_jsx(Gui, { children: _jsxs(DebugPanelProvider, { children: [children, _jsx(Stats, {}), _jsx(MemoryInfo, {})] }) }));
+}

package/dist/debug/components/Gui.d.ts

@@ -0,0 +1,20 @@
+import './Gui.module.css';
+import { type PropsWithChildren } from 'react';
+/**
+ * Initializes a GUI panel and shares it with the scene through context.
+ *
+ * The panel is created during render (with `autoPlace: false`, so the
+ * constructor has no DOM side effect), which makes it available to the scene
+ * synchronously on first render — no `null` phase to guard. The effect only
+ * attaches its `domElement` to the document and, on cleanup, calls `destroy()`,
+ * which detaches the element and clears child folders without invalidating the
+ * instance or its element. That keeps it StrictMode-safe: after the dev-only
+ * unmount/remount, the same element is re-attached and the scene's own effects
+ * re-add their folders. Rendered as an ancestor of the scene, so on unmount
+ * React tears the scene's folders down before this component destroys the panel.
+ * @param props - Component props; `children` is the scene subtree that consumes
+ *   the GUI via `useGui`.
+ * @returns The children wrapped with the GUI provided through context.
+ */
+export declare function Gui(props: PropsWithChildren): import("react").JSX.Element;
+//# sourceMappingURL=Gui.d.ts.map

package/dist/debug/components/Gui.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import './Gui.module.css'; // Global overrides of lil-gui's stock styling (checkbox row layout).
+import { GUI } from 'lil-gui';
+import { useEffect, useState } from 'react';
+import { GuiContext } from '../debug-context';
+/**
+ * Initializes a GUI panel and shares it with the scene through context.
+ *
+ * The panel is created during render (with `autoPlace: false`, so the
+ * constructor has no DOM side effect), which makes it available to the scene
+ * synchronously on first render — no `null` phase to guard. The effect only
+ * attaches its `domElement` to the document and, on cleanup, calls `destroy()`,
+ * which detaches the element and clears child folders without invalidating the
+ * instance or its element. That keeps it StrictMode-safe: after the dev-only
+ * unmount/remount, the same element is re-attached and the scene's own effects
+ * re-add their folders. Rendered as an ancestor of the scene, so on unmount
+ * React tears the scene's folders down before this component destroys the panel.
+ * @param props - Component props; `children` is the scene subtree that consumes
+ *   the GUI via `useGui`.
+ * @returns The children wrapped with the GUI provided through context.
+ */
+export function Gui(props) {
+    const { children } = props;
+    const [gui] = useState(() => new GUI({ autoPlace: false, closeFolders: true }));
+    useEffect(() => {
+        gui.domElement.classList.add('lil-auto-place', 'autoPlace');
+        document.body.appendChild(gui.domElement);
+        gui.close();
+        return () => gui.destroy();
+    }, [gui]);
+    return _jsx(GuiContext, { value: gui, children: children });
+}

package/dist/debug/components/MemoryInfo.d.ts

@@ -0,0 +1,22 @@
+/**
+ * GPU-memory debug panel backed by webgl-memory, shown bottom-left.
+ *
+ * The component lives inside the R3F `<Canvas>` tree so it can reach the
+ * renderer via `useThree`. The figures come from the `GMAN_webgl_memory` context
+ * extension that webgl-memory installs (see the debug entry, which loads it
+ * before the canvas context is created); this component only reads it, never
+ * imports the library.
+ *
+ * webgl-memory exposes no change event, so it samples the extension after every
+ * rendered frame and hands the snapshot to {@link Panel}. Without the
+ * extension — a context created before webgl-memory could instrument it —
+ * nothing ever fills the panel, and it stays visibly empty on purpose: a wrong
+ * readout is diagnosable where a missing one is not, and `prepareDebug` is what
+ * keeps that state out of practice. `getMemoryInfo` is
+ * cheap, and the panel skips its DOM update whenever the serialized readout is
+ * unchanged, so sampling unconditionally (rather than only while the panel is
+ * open) costs nothing visible.
+ * @returns The bottom-left GPU-memory panel.
+ */
+export declare function MemoryInfo(): import("react").JSX.Element;
+//# sourceMappingURL=MemoryInfo.d.ts.map

package/dist/debug/components/MemoryInfo.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { addAfterEffect, useThree } from '@react-three/fiber';
+import { useEffect, useState } from 'react';
+import { Panel } from './Panel';
+/**
+ * GPU-memory debug panel backed by webgl-memory, shown bottom-left.
+ *
+ * The component lives inside the R3F `<Canvas>` tree so it can reach the
+ * renderer via `useThree`. The figures come from the `GMAN_webgl_memory` context
+ * extension that webgl-memory installs (see the debug entry, which loads it
+ * before the canvas context is created); this component only reads it, never
+ * imports the library.
+ *
+ * webgl-memory exposes no change event, so it samples the extension after every
+ * rendered frame and hands the snapshot to {@link Panel}. Without the
+ * extension — a context created before webgl-memory could instrument it —
+ * nothing ever fills the panel, and it stays visibly empty on purpose: a wrong
+ * readout is diagnosable where a missing one is not, and `prepareDebug` is what
+ * keeps that state out of practice. `getMemoryInfo` is
+ * cheap, and the panel skips its DOM update whenever the serialized readout is
+ * unchanged, so sampling unconditionally (rather than only while the panel is
+ * open) costs nothing visible.
+ * @returns The bottom-left GPU-memory panel.
+ */
+export function MemoryInfo() {
+    const gl = useThree((state) => state.gl);
+    const [memoryInfo, setMemoryInfo] = useState(null);
+    useEffect(() => {
+        const ext = gl.getContext().getExtension('GMAN_webgl_memory');
+        if (!ext)
+            return;
+        return addAfterEffect(() => {
+            setMemoryInfo({ ...ext.getMemoryInfo(), drawCalls: gl.info.render.calls });
+        });
+    }, [gl]);
+    return _jsx(Panel, { corner: "left", label: "Memory Info", value: memoryInfo, replacer: localizeNumbers });
+}
+// `JSON.stringify` replacer: render numbers with locale thousands separators
+// (e.g. `1,048,576`).
+function localizeNumbers(_key, value) {
+    return typeof value === 'number' ? value.toLocaleString() : value;
+}

package/dist/debug/components/Panel.d.ts

@@ -0,0 +1,31 @@
+/** Props for {@link Panel}. */
+export interface PanelProps {
+    /** Which bottom corner the panel is pinned to. */
+    corner: 'left' | 'right';
+    /** Shown on the toggle button after "Show"/"Hide". */
+    label: string;
+    /** Value serialized to JSON and shown while the panel is open. */
+    value: unknown;
+    /** Optional `JSON.stringify` replacer, for custom formatting of the value. */
+    replacer?: (key: string, value: unknown) => unknown;
+}
+/**
+ * A collapsible debug readout pinned to a bottom corner, rendered as regular DOM
+ * outside the R3F reconciler. The reusable chrome extracted from the GPU-memory
+ * panel: a caller only supplies a corner, a label, and the `value` to display.
+ *
+ * A component inside the `<Canvas>` tree cannot return DOM — R3F's reconciler
+ * only understands Three.js objects, so a returned `<div>` (even via
+ * `createPortal`) never becomes real DOM. So, like drei's `<Html>`, it renders
+ * into a plain element created with `document.createElement` using react-dom's
+ * own root, and returns `null` to R3F.
+ *
+ * The interactive open state and serialization live in {@link PanelView}, inside
+ * that react-dom root, so toggling, style HMR, and value changes reconcile there
+ * without depending on the parent (or R3F) re-running an effect. This component
+ * only pushes the latest props into the root whenever they change.
+ * @param props - Corner, toggle label, and the value to display.
+ * @returns `null`.
+ */
+export declare function Panel(props: PanelProps): null;
+//# sourceMappingURL=Panel.d.ts.map

package/dist/debug/components/Panel.js

@@ -0,0 +1,98 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import styles from './Panel.module.css';
+/**
+ * The panel's DOM, rendered *inside* the detached react-dom root. The open state
+ * and the serialization live here — not on the parent {@link Panel} — so the
+ * toggle click, HMR of these styles, and value changes all reconcile as an
+ * ordinary react-dom subtree. If the parent diffed the markup by hand instead
+ * (keyed on a fixed dep list), anything outside that list — opening the panel,
+ * editing this CSS module — wouldn't show until the next value push happened to
+ * re-run it.
+ * @param props - Corner, toggle label, value to display, and optional replacer.
+ * @returns The panel element.
+ */
+function PanelView(props) {
+    const { corner, label, value } = props;
+    const [isOpen, setIsOpen] = useState(false);
+    function replacer(key, value) {
+        if (Array.isArray(value))
+            return `[${value.join(', ')}]`;
+        if (props.replacer)
+            return props.replacer(key, value);
+        return value;
+    }
+    function serialize() {
+        // Serialize only while open — the readout is hidden otherwise.
+        if (!isOpen)
+            return '';
+        // A single-key wrapper (e.g. `{ camera: {…} }`) is unwrapped to its value, so
+        // the readout shows the payload directly rather than one level of nesting.
+        let valueToSerialize = value;
+        if (typeof value === 'object' && value) {
+            const keys = Object.keys(value);
+            valueToSerialize = keys.length === 1 ? value[keys[0]] : value;
+        }
+        return JSON.stringify(valueToSerialize, replacer, 2).replaceAll('"', '');
+    }
+    return (_jsxs("div", { className: `${styles.container} ${styles[corner]}`, children: [_jsxs("button", { className: styles.toggle, onClick: () => setIsOpen((open) => !open), children: [isOpen ? 'Hide' : 'Show', " ", label] }), isOpen && _jsx("div", { className: styles.info, children: serialize() })] }));
+}
+/**
+ * A collapsible debug readout pinned to a bottom corner, rendered as regular DOM
+ * outside the R3F reconciler. The reusable chrome extracted from the GPU-memory
+ * panel: a caller only supplies a corner, a label, and the `value` to display.
+ *
+ * A component inside the `<Canvas>` tree cannot return DOM — R3F's reconciler
+ * only understands Three.js objects, so a returned `<div>` (even via
+ * `createPortal`) never becomes real DOM. So, like drei's `<Html>`, it renders
+ * into a plain element created with `document.createElement` using react-dom's
+ * own root, and returns `null` to R3F.
+ *
+ * The interactive open state and serialization live in {@link PanelView}, inside
+ * that react-dom root, so toggling, style HMR, and value changes reconcile there
+ * without depending on the parent (or R3F) re-running an effect. This component
+ * only pushes the latest props into the root whenever they change.
+ * @param props - Corner, toggle label, and the value to display.
+ * @returns `null`.
+ */
+export function Panel(props) {
+    const { corner, label, value, replacer } = props;
+    // Created imperatively, so R3F's reconciler never sees these DOM elements.
+    const [container] = useState(() => document.createElement('div'));
+    const rootRef = useRef(null);
+    const pendingUnmountRef = useRef(false);
+    // Mount the container and spin up a react-dom root once.
+    //
+    // Unmounting a nested root synchronously during the parent's commit warns
+    // "unmount while rendering", so the unmount is deferred to a microtask
+    // (Promise, not queueMicrotask — old WebViews lack it). That deferral has to
+    // be cancellable: under StrictMode the effect runs mount → unmount → mount,
+    // and the queued unmount can fire *after* the remount has already reused this
+    // root (react-dom flushes the microtask late, R3F's reconciler earlier). Left
+    // unguarded, the stale microtask would tear down the live panel. Every
+    // (re)mount clears `pendingUnmountRef`, so a superseded unmount skips itself;
+    // only a real unmount — with no remount to clear the flag — destroys the root.
+    useEffect(() => {
+        pendingUnmountRef.current = false;
+        document.body.appendChild(container);
+        const root = rootRef.current ?? createRoot(container);
+        rootRef.current = root;
+        return () => {
+            container.remove();
+            pendingUnmountRef.current = true;
+            void Promise.resolve().then(() => {
+                if (!pendingUnmountRef.current)
+                    return;
+                rootRef.current?.unmount();
+                rootRef.current = null;
+            });
+        };
+    }, [container]);
+    // Push the latest props into the detached root. PanelView reconciles as its own
+    // react-dom subtree, keeping its open state across these updates.
+    useEffect(() => {
+        rootRef.current?.render(_jsx(PanelView, { corner: corner, label: label, value: value, replacer: replacer }));
+    }, [corner, label, value, replacer]);
+    return null;
+}

package/dist/debug/components/Stats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Performance-stats overlay (frame rate, GPU timing, refresh rate) attached to
+ * the document body and refreshed after every rendered frame.
+ *
+ * The overlay is mounted imperatively, so the component renders nothing.
+ * @returns `null`.
+ */
+export declare function Stats(): null;
+//# sourceMappingURL=Stats.d.ts.map

package/dist/debug/components/Stats.js

@@ -0,0 +1,24 @@
+import { addAfterEffect, useThree } from '@react-three/fiber';
+import { useEffect } from 'react';
+import StatsGl from 'stats-gl';
+/**
+ * Performance-stats overlay (frame rate, GPU timing, refresh rate) attached to
+ * the document body and refreshed after every rendered frame.
+ *
+ * The overlay is mounted imperatively, so the component renders nothing.
+ * @returns `null`.
+ */
+export function Stats() {
+    const gl = useThree((state) => state.gl);
+    useEffect(() => {
+        const stats = new StatsGl({ trackGPU: true, trackHz: true });
+        void stats.init(gl);
+        document.body.appendChild(stats.domElement);
+        const removeAfterEffect = addAfterEffect(() => stats.update());
+        return () => {
+            stats.dispose();
+            removeAfterEffect();
+        };
+    }, [gl]);
+    return null;
+}

package/dist/debug/debug-context.d.ts

@@ -0,0 +1,41 @@
+import type { GUI } from 'lil-gui';
+/**
+ * Context carrying the active debug GUI, or `null` when the debug UI is
+ * disabled or has not finished loading. Isolated in its own module (with a
+ * type-only GUI import) so components can read the GUI without pulling the
+ * debug UI bundle into the main chunk.
+ */
+export declare const GuiContext: import("react").Context<GUI | null>;
+/**
+ * Reads the active debug GUI from context.
+ *
+ * Returns `null` while the debug UI is off or still loading, so guard on a
+ * non-null value before adding folders or controllers.
+ * @returns The current GUI instance, or `null`.
+ */
+export declare const useGui: () => GUI | null;
+/** Write API for the debug panel: components publish key/value entries that the panel combines into one object and renders. */
+export interface DebugPanel {
+    /** Adds or updates the entry under `key`. */
+    set(key: string, value: unknown): void;
+    /** Removes the entry under `key`. */
+    remove(key: string): void;
+}
+/**
+ * Context carrying the debug panel's write API, or `null` when the debug UI is
+ * disabled. Kept separate from {@link GuiContext} so panel updates never
+ * re-render GUI consumers and vice versa.
+ */
+export declare const DebugPanelContext: import("react").Context<DebugPanel | null>;
+/**
+ * Returns a setter that publishes a key/value entry to the debug panel.
+ *
+ * The returned `set(key, value)` is stable and safe to call from anywhere,
+ * including a per-frame loop — it never re-renders the calling tree, and the
+ * panel itself re-renders only when its combined, serialized value changes.
+ * Every key a component writes is removed automatically when it unmounts.
+ * Outside the debug provider the setter is a no-op.
+ * @returns A `set(key, value)` function for the debug panel.
+ */
+export declare function useDebugPanel(): (key: string, value: unknown) => void;
+//# sourceMappingURL=debug-context.d.ts.map

package/dist/debug/debug-context.js

@@ -0,0 +1,59 @@
+import { createContext, use, useEffect, useRef } from 'react';
+/**
+ * Context carrying the active debug GUI, or `null` when the debug UI is
+ * disabled or has not finished loading. Isolated in its own module (with a
+ * type-only GUI import) so components can read the GUI without pulling the
+ * debug UI bundle into the main chunk.
+ */
+export const GuiContext = createContext(null);
+/**
+ * Reads the active debug GUI from context.
+ *
+ * Returns `null` while the debug UI is off or still loading, so guard on a
+ * non-null value before adding folders or controllers.
+ * @returns The current GUI instance, or `null`.
+ */
+export const useGui = () => use(GuiContext);
+/**
+ * Context carrying the debug panel's write API, or `null` when the debug UI is
+ * disabled. Kept separate from {@link GuiContext} so panel updates never
+ * re-render GUI consumers and vice versa.
+ */
+export const DebugPanelContext = createContext(null);
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const noop = () => { };
+/**
+ * Returns a setter that publishes a key/value entry to the debug panel.
+ *
+ * The returned `set(key, value)` is stable and safe to call from anywhere,
+ * including a per-frame loop — it never re-renders the calling tree, and the
+ * panel itself re-renders only when its combined, serialized value changes.
+ * Every key a component writes is removed automatically when it unmounts.
+ * Outside the debug provider the setter is a no-op.
+ * @returns A `set(key, value)` function for the debug panel.
+ */
+export function useDebugPanel() {
+    const panel = use(DebugPanelContext);
+    // One stable Set per consumer, tracking every key it has published. The
+    // compiler memoizes the allocation, so subsequent renders don't churn it; even
+    // without the compiler, useRef discards the extra `new Set()` after mount.
+    const keysRef = useRef(new Set());
+    useEffect(() => {
+        // Outside the debug provider there is nothing to clean up.
+        if (!panel)
+            return;
+        // Capture the (stable) Set locally so the cleanup closure doesn't read a ref
+        // in teardown. Every key this component published is removed on unmount.
+        const tracked = keysRef.current;
+        return () => tracked.forEach((key) => panel.remove(key));
+    }, [panel]);
+    // Non-debug consumers share one stable no-op — no per-consumer closure.
+    if (!panel)
+        return noop;
+    // Stable identity comes from the React Compiler — no hand-written useCallback —
+    // so callers can put `set` in effect deps without churn.
+    return (key, value) => {
+        keysRef.current.add(key);
+        panel.set(key, value);
+    };
+}