@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/core/text/batched-text-material.js

@@ -0,0 +1,123 @@
+import { openMain } from '../shader-source';
+/**
+ * The material side of a text batch: what troika's derivation has to become before it can draw a
+ * batch's members, and where the batch's per-instance uniforms are declared.
+ *
+ * Troika builds that material in two moments with its own derivation between them, so the work
+ * splits the same way — {@link patchBaseMaterial} runs on the base material *before*
+ * `createDerivedMaterial`, {@link configureDerivedMaterial} on the result *after*. Each order is
+ * load-bearing; see the two.
+ *
+ * Free functions holding no state, as `instanced-material.ts` is. What is per-batch — which material
+ * has already been wrapped — stays on the batch.
+ */
+/** The per-member index attribute troika's batch material declares, and the uniforms texture indexes by. */
+export const MEMBER_INDEX_ATTRIBUTE = 'aTroikaTextBatchMemberIndex';
+/**
+ * Wraps a base material's `onBeforeCompile` so a batch's per-instance uniforms are declared ahead of
+ * anything the material itself patches in.
+ *
+ * The prologue goes on the **base**, ahead of troika's rewrite: troika calls the base material's
+ * handler first and then rebuilds `main` around it, renaming the original `troikaOrigMain`.
+ * Injecting here puts the prologue and whatever the material patches in on the same side of that
+ * rename, so a material patch reading a per-instance uniform finds it in scope; injecting from the
+ * derived handler instead would strand the two in different functions.
+ *
+ * Call once per material — a second wrap would nest, and the caller holds the memo that prevents it.
+ * @param material - The base material troika derives from.
+ * @param uniforms - The batch's per-instance uniforms.
+ */
+export function patchBaseMaterial(material, uniforms) {
+    const onBeforeCompileBase = material.onBeforeCompile.bind(material);
+    material.onBeforeCompile = (shader, renderer) => {
+        uniforms.patchShader(shader, MEMBER_INDEX_ATTRIBUTE);
+        onBeforeCompileBase(shader, renderer);
+    };
+}
+/**
+ * Finishes troika's derivation: reverts its two impositions on the base, and installs the one shader
+ * hook a batch needs.
+ * @param derived - What `createDerivedMaterial` returned.
+ * @param base - The material it was derived from.
+ * @param uniforms - The batch's per-instance uniforms, whose presence the program is cached by.
+ * @returns `derived`.
+ */
+export function configureDerivedMaterial(derived, base, uniforms) {
+    // troika forces `transparent = true` on every derived text material, which moves the batch into
+    // three's *transparent* render list — drawn after every opaque object regardless of `renderOrder`,
+    // so text would always cover the layers above it. Our base materials get alpha blending from
+    // `CustomBlending` instead (objects/materials/shared.ts), so this restores what the base asked for.
+    // Everything else troika leaves alone already delegates to the base through the prototype chain.
+    derived.transparent = base.transparent;
+    // With `transparent` reverted the batch renders from three's *opaque* list, which
+    // `painterSortStable` orders by `material.id` — and troika builds its outline material with
+    // `id + 0.1`, so the preliminary outline pass would sort *after* the fill and paint over it. (Its
+    // own forced transparency hid this: the transparent list sorts by depth, with no `material.id`
+    // term.) Building it here, with a lower id, restores the intended order; troika's getter finds it
+    // already cached and uses it.
+    derived._outlineMtl = makeOutlineMaterial(derived);
+    // Recompile when the uniform schema changes, since that changes the generated GLSL. The whole
+    // schema, not just whether a texture exists: two batches declaring different uniforms compile
+    // different source, and three compares nothing but this key.
+    const cacheKeyBase = derived.customProgramCacheKey.bind(derived);
+    derived.customProgramCacheKey = () => `efpText_${uniforms.shaderKey}|${cacheKeyBase()}`;
+    // Assignment, *not* the read-bind-wrap pattern the sibling meshes use: troika defines
+    // `onBeforeCompile` as an accessor pair whose getter returns troika's own handler and whose setter
+    // stashes ours (troika-three-utils DerivedMaterial), so calling through the getter from inside our
+    // handler would re-enter troika's, which calls ours again. Troika invokes this one last, after its
+    // shader upgrade, which is the only thing that has to be true.
+    derived.onBeforeCompile = (shader) => {
+        // Late by necessity: troika's own `vertexTransform` *reads* this offset, and the transform runs
+        // from the main it builds, ahead of the base's. Initializing any earlier would leave the
+        // transform reading the garbage this exists to prevent.
+        shader.vertexShader = openMain(shader.vertexShader, POSITION_OFFSET_INIT);
+    };
+    return derived;
+}
+/**
+ * Whether a material draws through the batched text shader — the only thing a batch's per-draw
+ * texture fill asks of the material it is handed.
+ *
+ * `isTroikaTextMaterial`, which upstream tests instead, does not establish that. Troika sets it on
+ * the text derivation, which the batch's material only sits on top of — so a plain unbatched `Text`
+ * material carries the flag too, and filling one would write matrices its shader never reads. The
+ * uniforms are the honest test: a batch derives over a link that declares them, an unbatched `Text`
+ * never does, and every derivation merges its base's uniform map forward, so they survive into any
+ * sibling built by calling `material.constructor`.
+ * @param material - The material three is about to draw with.
+ * @returns Whether it reads its transforms from a matrix texture.
+ */
+export function readsMemberMatrices(material) {
+    return !!material.uniforms?.uTroikaMatricesTexture;
+}
+/**
+ * Builds the outline pass's material: troika's own recipe, with the id inverted.
+ *
+ * Prototype-chained to the fill material so it shares every uniform and shader, exactly as troika
+ * does — the two differ only in `isTextOutlineMaterial`, which is what the per-draw fill branches on
+ * to write the outline row of the data texture.
+ * @param derived - The fill material to derive the outline pass from.
+ * @returns The outline material.
+ */
+function makeOutlineMaterial(derived) {
+    const outline = Object.create(derived, {
+        // Below the fill, not above it: three's opaque sort is ascending by `material.id`, and the
+        // outline is a *preliminary* pass. A fraction keeps it clear of every integer material id.
+        id: { value: derived.id - 0.5 },
+    });
+    outline.isTextOutlineMaterial = true;
+    outline.depthWrite = false;
+    outline.map = null;
+    // troika disposes its own outline material with the fill; matched so replacing it leaks nothing.
+    derived.addEventListener('dispose', function onDispose() {
+        derived.removeEventListener('dispose', onDispose);
+        outline.dispose();
+    });
+    return outline;
+}
+/**
+ * Seeds the position-offset varying. An uninitialized varying reads as garbage on some Samsung/Mali
+ * drivers, and troika's `vertexTransform` only assigns this one in the outline branch — so the main
+ * pass would never write it at all.
+ */
+const POSITION_OFFSET_INIT = /* glsl */ `uTroikaPositionOffset = vec2(0.0);`;

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

@@ -0,0 +1,17 @@
+import { type GlyphsGeometry, type TextRenderInfo } from 'troika-three-text';
+import { type TextImpl } 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) => TextImpl | 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,50 @@
+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) => {
+                // An existing key keeps the slot it already holds, because the spread writes it in place.
+                if (key in prev)
+                    return Object.is(prev[key], value) ? prev : { ...prev, [key]: value };
+                // A key arrives for the first time, so rebuild the object in name order. Insertion order is
+                // what the readout prints, and a key that a publisher removes on unmount would otherwise
+                // come back at the bottom. `Object.fromEntries` needs Chrome 73, so build the object here.
+                const next = {};
+                for (const name of [...Object.keys(prev), key].sort()) {
+                    next[name] = name === key ? value : prev[name];
+                }
+                return next;
+            });
+        },
+        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,22 @@
+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.
+ * It also registers the panel's single change handler, which asks for a redraw. Every folder in the
+ * panel inherits it, so no controller carries one of its own.
+ * @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,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import './Gui.module.css'; // Global overrides of lil-gui's stock styling (checkbox row layout).
+import { useThree } from '@react-three/fiber';
+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.
+ * It also registers the panel's single change handler, which asks for a redraw. Every folder in the
+ * panel inherits it, so no controller carries one of its own.
+ * @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 }));
+    const invalidate = useThree((state) => state.invalidate);
+    useEffect(() => {
+        gui.domElement.classList.add('lil-auto-place', 'autoPlace');
+        document.body.appendChild(gui.domElement);
+        gui.close();
+        // One handler for the whole panel: lil-gui walks a changed controller up its parent chain, so
+        // this fires for every controller in every folder and no folder registers its own. It calls
+        // whichever `invalidate` the current mount installed — in the external embed `ExternalCanvas`
+        // replaces it with the host's `requestFrame`, which is how a GUI change reaches a host that owns
+        // the frame.
+        gui.onChange(() => invalidate());
+        return () => gui.destroy();
+    }, [gui, invalidate]);
+    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,104 @@
+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;
+        }
+        // `JSON.stringify` returns `undefined`, not a string, for a value that JSON cannot hold: the
+        // value `undefined` itself, or a function. The unwrap above exposes such a value, because a
+        // lone entry becomes the whole value. A wrapper of two entries hides it, because
+        // `JSON.stringify` drops the key. An empty string keeps the readout blank, so a publisher can
+        // push any value and the panel still renders.
+        const json = JSON.stringify(valueToSerialize, replacer, 2) ?? '';
+        return json.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