@expofp/renderer 3.2.4 → 3.27.0

package/dist/events/layout-targets.js

@@ -0,0 +1,245 @@
+import { createContext, use, useEffect } from 'react';
+import { isLayerDef } from '../types/guards';
+import { writeChanged } from '../update';
+import { createLogger } from '../utils/logging';
+import { culledBy } from './def-culling';
+const logger = createLogger('layout');
+/**
+ * The renderer's re-layout registry. Absent outside a renderer, where a layer simply registers
+ * nothing — which is what lets `Layer` be rendered bare in a spec.
+ */
+export const LayoutTargetsContext = createContext(undefined);
+/**
+ * Registers a layer's re-layout targets for as long as the layer is mounted: the defs it holds that
+ * declare an `onScale`, and the layer itself when it declares one.
+ *
+ * A child *layer* is never registered here even when it declares a handler — it registers itself, and
+ * it has to: a handler assigned to a layer after mount re-renders that layer alone, so a registration
+ * held by its parent would never learn of it. Self-registration also covers the root, which has no
+ * parent layer to be registered by.
+ *
+ * Called from the layer rather than from its containers or their instances, because this is where
+ * both halves are already at hand. It also means a def is laid out whether or not its instance has
+ * mounted — defs are the source of truth, and a staged mount picks up whatever they hold when it
+ * admits them.
+ *
+ * Outside a renderer there is no registry and this does nothing, which is what lets a `Layer` be
+ * rendered bare in a spec.
+ * @param layer - The layer registering; itself a target when it declares a handler, which is how a
+ *   layer whose *membership* depends on the camera re-derives it.
+ * @param children - The layer's children snapshot.
+ */
+export function useLayoutTargets(layer, children) {
+    const targets = use(LayoutTargetsContext);
+    useEffect(() => {
+        if (!targets)
+            return undefined;
+        const defs = children.filter((def) => (def.onScale !== undefined || def.onRoll !== undefined) && !isLayerDef(def));
+        if (layer.onScale || layer.onRoll)
+            defs.push(layer);
+        if (!defs.length)
+            return undefined;
+        return targets.register(defs);
+    }, [targets, layer, children]);
+}
+/**
+ * Builds a renderer's re-layout registry.
+ * @param invalidate - Requests a frame, for layouts that happen outside the frame loop.
+ * @param pixelSize - The pixel size defs are laid out at until the first frame moves it.
+ * @param roll - The roll defs are laid out at until the first frame moves it, in radians.
+ * @returns The registry.
+ */
+export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
+    const groups = new Set();
+    /**
+     * The pixel size each def was last laid out at — the whole of the registry's state, because the
+     * rule that lays a def out is the def's own. Keyed by def rather than by group, so a membership
+     * change re-lays out only the defs that joined.
+     *
+     * A def whose `onScale` is *replaced* after it was laid out is not noticed: the record says only
+     * "laid out at this size". Reassigning a handler is a thing nothing does — a def is built with its
+     * rule — and a caller that does it lays the def out itself.
+     */
+    const layouts = new WeakMap();
+    /**
+     * The roll each def's `onRoll` last ran at — the other axis's record, kept apart from
+     * {@link layouts} because the two move independently: a zoom leaves every roll record current,
+     * and a turn leaves every scale record current.
+     */
+    const rolls = new WeakMap();
+    /**
+     * The sweep's backlog: defs an `apply` marked stale and {@link LayoutTargets.drain} has not
+     * reached. **One queue for every axis** — which of a queued def's rules actually runs is decided
+     * at drain time by the per-axis records above, so a def stale on both axes is dequeued once and
+     * laid out on both, and a new axis adds a record and a rule, never another queue. `deferred`
+     * holds the ones a drain pushed behind the visible — hidden defs, and defs the frustum
+     * rejected — worked off with whatever budget the stale pass leaves. Sets, not arrays, because one
+     * def can be re-marked while queued and must not be laid out twice.
+     */
+    const pending = new Set();
+    const deferred = new Set();
+    let current = pixelSize;
+    let currentRoll = roll;
+    /**
+     * The view every rule is handed — one instance for the registry's lifetime, mutated as the axes
+     * move, which is what keeps a ten-thousand-label sweep allocation-free. `LayoutView` documents
+     * the flip side: valid during the call, so a rule destructures rather than retains it.
+     */
+    const view = { pixelSize: current, roll: currentRoll };
+    /**
+     * Runs a def's handler and writes the result.
+     *
+     * A leaf goes through the def's own registered sync — the same closure the React path runs after
+     * `update(def)` — so a handler mutating def fields needs no `update()` call of its own, and the two
+     * paths cannot disagree about what a def looks like. A def whose instance has not mounted yet syncs
+     * to nothing here and picks the mutation up when it does. A layer among the returned defs is
+     * reconciled instead, which is how a handler changes its own membership.
+     *
+     * A handler reporting nothing skips that write, which is the whole point of the return value: it is
+     * the half that costs. The def is still recorded as laid out, so a membership change does not run
+     * the handler over it again.
+     * @param def - The def to lay out.
+     * @returns Whether anything was written.
+     */
+    function layOut(def) {
+        // Hidden defs are laid out too. Whether a def draws at all can be exactly what its rule decides
+        // — a booth's dot appears only once the plan is far enough out for its label to stop fitting —
+        // so a registry that skipped them would never run the rule that would bring them back. Skipping
+        // the *waste* is the rule's own job instead: a handler with nothing worth drawing returns
+        // nothing, and the slot write is the half that costs.
+        if (!def.onScale || layouts.get(def) === current)
+            return false;
+        const changed = def.onScale(view);
+        // Recorded before the write, which runs the def's own sync and can reach back in here.
+        layouts.set(def, current);
+        if (!changed || changed.length === 0)
+            return false;
+        writeChanged(changed);
+        return true;
+    }
+    /**
+     * Runs a def's roll rule and writes the result — {@link layOut} on the other axis, with the same
+     * record-before-write ordering and the same "an empty return skips the write" contract.
+     * @param def - The def to lay out.
+     * @returns Whether anything was written.
+     */
+    function layOutRoll(def) {
+        if (!def.onRoll || rolls.get(def) === currentRoll)
+            return false;
+        const changed = def.onRoll(view);
+        rolls.set(def, currentRoll);
+        if (!changed || changed.length === 0)
+            return false;
+        writeChanged(changed);
+        return true;
+    }
+    /**
+     * Runs whatever of a def's rules are stale by their records — the one unit of work a dequeued def
+     * costs, scale before roll so a rule that turns a label re-fits it at the size just applied.
+     * @param def - The def to lay out.
+     * @returns Whether anything was written.
+     */
+    function layOutStale(def) {
+        const scaled = layOut(def);
+        const rolled = layOutRoll(def);
+        return scaled || rolled;
+    }
+    /**
+     * Marks stale defs for the sweep: the previous sweep's deferrals rejoin the queue — where the new
+     * frustum decides their priority afresh, and cross-axis work survives whichever axis moved — and
+     * every def carrying the moved axis's rule is (re-)queued.
+     * @param carriesRule - Whether a def declares the moved axis's rule.
+     */
+    function requeue(carriesRule) {
+        for (const def of deferred)
+            pending.add(def);
+        deferred.clear();
+        // Rule presence is read at marking time, so a rule cleared after registration — a hidden
+        // bookmark's — simply stops queueing, with nothing to unregister.
+        for (const defs of groups) {
+            for (const def of defs) {
+                if (carriesRule(def))
+                    pending.add(def);
+            }
+        }
+    }
+    return {
+        get pixelSize() {
+            return current;
+        },
+        get roll() {
+            return currentRoll;
+        },
+        get hasWork() {
+            return pending.size > 0 || deferred.size > 0;
+        },
+        register(defs) {
+            groups.add(defs);
+            let laidOut = false;
+            for (const def of defs) {
+                if (layOutStale(def))
+                    laidOut = true;
+            }
+            // Registration happens in an effect rather than inside the frame loop, so anything written here
+            // needs a frame asking for it.
+            if (laidOut)
+                invalidate();
+            return () => {
+                groups.delete(defs);
+                // A queued def whose layer is gone must not be laid out from the backlog: its instances are
+                // unmounting, and its handler may read state its owner already tore down.
+                for (const def of defs) {
+                    pending.delete(def);
+                    deferred.delete(def);
+                }
+            };
+        },
+        applyScale(nextPixelSize) {
+            current = nextPixelSize;
+            view.pixelSize = nextPixelSize;
+            requeue((def) => def.onScale !== undefined);
+        },
+        applyRoll(nextRoll) {
+            currentRoll = nextRoll;
+            view.roll = nextRoll;
+            requeue((def) => def.onRoll !== undefined);
+        },
+        drain(frustum, budgetMs = -1) {
+            if (pending.size === 0 && deferred.size === 0)
+                return false;
+            const start = performance.now();
+            const overBudget = () => budgetMs > 0 && performance.now() - start >= budgetMs;
+            let wrote = 0;
+            // Sets iterate in insertion order and tolerate deletion mid-walk, which is what makes the two
+            // passes below plain loops: the order moves arrived is the priority within a pass, and a
+            // processed def leaves its set before its rules run.
+            for (const def of pending) {
+                if (overBudget())
+                    break;
+                pending.delete(def);
+                // Deferral is priority, never a skip: a hidden def, or one the camera cannot see, joins the
+                // second pass rather than being laid out now. `def.hidden` needs no frustum — hidden is not
+                // drawn wherever it sits.
+                if (def.hidden === true || (frustum !== undefined && culledBy(def, frustum))) {
+                    deferred.add(def);
+                    continue;
+                }
+                if (layOutStale(def))
+                    wrote++;
+            }
+            for (const def of deferred) {
+                if (overBudget())
+                    break;
+                deferred.delete(def);
+                if (layOutStale(def))
+                    wrote++;
+            }
+            const remaining = pending.size + deferred.size;
+            if (wrote > 0) {
+                const took = (performance.now() - start).toFixed(2);
+                logger.debug(`laid out ${wrote} defs (${remaining} remaining) in ${took}ms`);
+            }
+            return remaining > 0;
+        },
+    };
+}

package/dist/events/pointer.d.ts

@@ -0,0 +1,118 @@
+import { type ThreeEvent } from '@react-three/fiber';
+import { type Intersection, type Object3D, type Ray, type Raycaster } from 'three';
+import { type PlanPoint, type Space } from '../space/Space';
+import { type LayerDef, type RenderableDef } from '../types/defs';
+import { type PointerHandlerName } from '../types/events';
+/**
+ * Traces one mesh's intersection back to the def that drew it, or `undefined` when it cannot —
+ * a slot released between the raycast and the dispatch, or a mesh whose picking is not implemented.
+ */
+export type HitResolver = (hit: Intersection) => RenderableDef | undefined;
+/** The picking props {@link usePointerProps} builds for a layer's `<group>`. */
+export interface PointerGroupProps {
+    /** Refuses the raycast traversal into the subtree while the layer is off screen. */
+    raycast(): false | undefined;
+    /** Dispatches a click in the layer's subtree; attached only when the def declares one. */
+    onClick?: (event: ThreeEvent<MouseEvent>) => void;
+    /** Dispatches a move over the layer's subtree; attached only when the def declares one. */
+    onPointerMove?: (event: ThreeEvent<MouseEvent>) => void;
+    /** Dispatches the pointer leaving a def; attached only when the def declares one. */
+    onPointerOut?: (event: ThreeEvent<MouseEvent>) => void;
+}
+/**
+ * The props that make a layer's group interactive: one dispatching handler per handler the def
+ * declares, and the raycast gate that un-picks the layer while it is off screen.
+ *
+ * Presence is the contract, in both directions. R3F raycasts only objects carrying handlers — and
+ * raycasts them with their whole subtree — so a handler is attached exactly when the def declares
+ * one and the layer is on screen: a layer wanting clicks alone must not be raycast on every pointer
+ * move, and a layer that is hidden, or under something hidden, must not be raycast at all. Which
+ * function a handler currently is stays out of it: dispatch looks the handler up by name on the def
+ * at event time, so swapping one takes effect with no render.
+ *
+ * Handler presence is read here as values (`layer.onClick !== undefined`) rather than through
+ * `layer` inside a callback: memoization compares what a render *read*, and a property reached only
+ * from inside a function is not that — a compiled cache keyed on the def object, whose identity
+ * never changes, would keep serving a group with no handler attached.
+ *
+ * The `raycast` gate covers the direction handler absence cannot: an interactive *ancestor* is
+ * raycast with everything beneath it, and `false` is three's own signal to stop descending —
+ * `Raycaster`'s `intersect()` keeps walking a subtree only while each object's `raycast` returns
+ * something other than `false`. Visibility is read at raycast time rather than swapped per render,
+ * since R3F ignores a prop set to `undefined` and a blocking version would stick.
+ * @param layer - The layer the group renders.
+ * @param visible - Whether the layer is on screen, ancestors included.
+ * @returns Props to spread onto the layer's `<group>`.
+ */
+export declare function usePointerProps(layer: LayerDef, visible: boolean): PointerGroupProps;
+/**
+ * Hands one of R3F's intersection events to a layer's handler, as the narrow event the public API
+ * describes: the def that was hit, and where the pointer sits on the plan plane.
+ *
+ * Two hits are dropped rather than reported. One the renderer cannot trace to a def — a released
+ * slot, or a mesh whose picking is not implemented — because a handler has nothing to act on without
+ * it. And a click that ends a drag: R3F fires `onClick` on release whenever the press landed on the
+ * same object, which on a pannable plan would select whatever the pan started over.
+ *
+ * The handler is called with no receiver, so a handler shared across layers reads `event.def` rather
+ * than the layer it was declared on.
+ * @param layer - The layer whose handler should run.
+ * @param name - Which handler to run.
+ * @param event - R3F's intersection event.
+ * @param space - The scene's space, which the event's world coordinates are reported through.
+ */
+export declare function dispatchPointer(layer: LayerDef, name: PointerHandlerName, event: ThreeEvent<MouseEvent>, space: Space): void;
+/**
+ * Registers how a mesh's intersections map back to defs, for as long as the mesh is mounted.
+ *
+ * Each container knows two things no one else does: which field of an intersection identifies its
+ * slot (`batchId` for a batched mesh, `instanceId` for an instanced one, the pack position for a line
+ * batch), and which def holds that slot. It supplies both here as one closure, so the dispatch path
+ * stays free of per-mesh-type knowledge.
+ * @param mesh - The mesh whose hits the resolver speaks for.
+ * @param resolve - Maps one of its intersections to a def.
+ * @returns An unregister function, safe to call after another resolver replaced this one.
+ */
+export declare function registerHitResolver(mesh: Object3D, resolve: HitResolver): () => void;
+/**
+ * The def an intersection hit.
+ *
+ * A mesh with no registered resolver reports nothing, which is how a primitive whose picking is not
+ * implemented behaves as if its layer were not interactive: the hit is dropped and no handler runs.
+ * @param hit - The intersection to trace.
+ * @returns The def, or `undefined` when the hit cannot be traced to one.
+ */
+export declare function resolveHit(hit: Intersection): RenderableDef | undefined;
+/**
+ * Where a missed click landed, in plan units.
+ *
+ * **A miss is not an empty canvas.** It means no handler took the click: a layer declaring no
+ * pointer handlers is never raycast by R3F in the first place, so the pointer may be sitting
+ * squarely on a wall, a model or a booth that simply does not listen. Searching the scene here is
+ * what makes the reported position agree with what the user is looking at — the same answer a hit
+ * event carries, arrived at a moment later and with no def to name.
+ *
+ * The search prunes hidden content for free: {@link usePointerProps} refuses the traversal into a
+ * hidden layer's subtree, which is three's own signal to stop descending.
+ * @param raycaster - The scene's raycaster, holding the ray R3F cast for this click.
+ * @param scene - The scene to search.
+ * @param space - The scene's space.
+ * @returns The nearest geometry under the pointer, or — where there is none — the floor beneath it.
+ */
+export declare function missedPoint(raycaster: Raycaster, scene: Object3D, space: Space): PlanPoint;
+/**
+ * Where a ray crosses the plan plane — the floor under the pointer, whatever is drawn above it.
+ *
+ * The fallback for a click that reached neither a handler nor any geometry at all: past the edge of
+ * the plan there is nothing to report but the ground the ray carries on to.
+ *
+ * Both the crossing and the fallback are taken through the scene's space, because R3F casts its rays
+ * in world coordinates and a scene fitted to the canvas draws a plan unit as some other number of
+ * those. Without it the reported position is the world one wearing plan units' name.
+ * @param ray - The ray the pointer cast, in world space.
+ * @param space - The scene's space.
+ * @returns The crossing, in plan units, or — for a ray running parallel to the plan, which crosses
+ *   it nowhere — where the ray started.
+ */
+export declare function planePoint(ray: Ray, space: Space): PlanPoint;
+//# sourceMappingURL=pointer.d.ts.map

package/dist/events/pointer.js

@@ -0,0 +1,168 @@
+import { useSpace } from '../space/Space';
+/**
+ * The props that make a layer's group interactive: one dispatching handler per handler the def
+ * declares, and the raycast gate that un-picks the layer while it is off screen.
+ *
+ * Presence is the contract, in both directions. R3F raycasts only objects carrying handlers — and
+ * raycasts them with their whole subtree — so a handler is attached exactly when the def declares
+ * one and the layer is on screen: a layer wanting clicks alone must not be raycast on every pointer
+ * move, and a layer that is hidden, or under something hidden, must not be raycast at all. Which
+ * function a handler currently is stays out of it: dispatch looks the handler up by name on the def
+ * at event time, so swapping one takes effect with no render.
+ *
+ * Handler presence is read here as values (`layer.onClick !== undefined`) rather than through
+ * `layer` inside a callback: memoization compares what a render *read*, and a property reached only
+ * from inside a function is not that — a compiled cache keyed on the def object, whose identity
+ * never changes, would keep serving a group with no handler attached.
+ *
+ * The `raycast` gate covers the direction handler absence cannot: an interactive *ancestor* is
+ * raycast with everything beneath it, and `false` is three's own signal to stop descending —
+ * `Raycaster`'s `intersect()` keeps walking a subtree only while each object's `raycast` returns
+ * something other than `false`. Visibility is read at raycast time rather than swapped per render,
+ * since R3F ignores a prop set to `undefined` and a blocking version would stick.
+ * @param layer - The layer the group renders.
+ * @param visible - Whether the layer is on screen, ancestors included.
+ * @returns Props to spread onto the layer's `<group>`.
+ */
+export function usePointerProps(layer, visible) {
+    // Pointer positions are reported on the plan, and R3F casts its rays in world coordinates.
+    const space = useSpace();
+    const handlesClick = visible && layer.onClick !== undefined;
+    const handlesPointerMove = visible && layer.onPointerMove !== undefined;
+    const handlesPointerOut = visible && layer.onPointerOut !== undefined;
+    function handler(name) {
+        return (event) => dispatchPointer(layer, name, event, space);
+    }
+    return {
+        raycast: () => (visible ? undefined : false),
+        onClick: handlesClick ? handler('onClick') : undefined,
+        onPointerMove: handlesPointerMove ? handler('onPointerMove') : undefined,
+        onPointerOut: handlesPointerOut ? handler('onPointerOut') : undefined,
+    };
+}
+/**
+ * Hands one of R3F's intersection events to a layer's handler, as the narrow event the public API
+ * describes: the def that was hit, and where the pointer sits on the plan plane.
+ *
+ * Two hits are dropped rather than reported. One the renderer cannot trace to a def — a released
+ * slot, or a mesh whose picking is not implemented — because a handler has nothing to act on without
+ * it. And a click that ends a drag: R3F fires `onClick` on release whenever the press landed on the
+ * same object, which on a pannable plan would select whatever the pan started over.
+ *
+ * The handler is called with no receiver, so a handler shared across layers reads `event.def` rather
+ * than the layer it was declared on.
+ * @param layer - The layer whose handler should run.
+ * @param name - Which handler to run.
+ * @param event - R3F's intersection event.
+ * @param space - The scene's space, which the event's world coordinates are reported through.
+ */
+export function dispatchPointer(layer, name, event, space) {
+    const handler = layer[name];
+    if (!handler)
+        return;
+    if (name === 'onClick' && isDrag(event))
+        return;
+    const def = resolveHit(event);
+    if (!def)
+        return;
+    handler({
+        def,
+        // The ray's own intersection with the geometry, which three computed against the real
+        // triangles — so an elevated def reports the point on *it*, elevation and all, rather than the
+        // ground the ray carries on to behind it. R3F reports it in world coordinates; the cast is the
+        // assertion of which space that is.
+        point: space.worldToPlan(event.point),
+        stopPropagation: () => event.stopPropagation(),
+        nativeEvent: event.nativeEvent,
+    });
+}
+/**
+ * Registers how a mesh's intersections map back to defs, for as long as the mesh is mounted.
+ *
+ * Each container knows two things no one else does: which field of an intersection identifies its
+ * slot (`batchId` for a batched mesh, `instanceId` for an instanced one, the pack position for a line
+ * batch), and which def holds that slot. It supplies both here as one closure, so the dispatch path
+ * stays free of per-mesh-type knowledge.
+ * @param mesh - The mesh whose hits the resolver speaks for.
+ * @param resolve - Maps one of its intersections to a def.
+ * @returns An unregister function, safe to call after another resolver replaced this one.
+ */
+export function registerHitResolver(mesh, resolve) {
+    resolvers.set(mesh, resolve);
+    return () => {
+        if (resolvers.get(mesh) === resolve)
+            resolvers.delete(mesh);
+    };
+}
+/**
+ * The def an intersection hit.
+ *
+ * A mesh with no registered resolver reports nothing, which is how a primitive whose picking is not
+ * implemented behaves as if its layer were not interactive: the hit is dropped and no handler runs.
+ * @param hit - The intersection to trace.
+ * @returns The def, or `undefined` when the hit cannot be traced to one.
+ */
+export function resolveHit(hit) {
+    return resolvers.get(hit.object)?.(hit);
+}
+/**
+ * Where a missed click landed, in plan units.
+ *
+ * **A miss is not an empty canvas.** It means no handler took the click: a layer declaring no
+ * pointer handlers is never raycast by R3F in the first place, so the pointer may be sitting
+ * squarely on a wall, a model or a booth that simply does not listen. Searching the scene here is
+ * what makes the reported position agree with what the user is looking at — the same answer a hit
+ * event carries, arrived at a moment later and with no def to name.
+ *
+ * The search prunes hidden content for free: {@link usePointerProps} refuses the traversal into a
+ * hidden layer's subtree, which is three's own signal to stop descending.
+ * @param raycaster - The scene's raycaster, holding the ray R3F cast for this click.
+ * @param scene - The scene to search.
+ * @param space - The scene's space.
+ * @returns The nearest geometry under the pointer, or — where there is none — the floor beneath it.
+ */
+export function missedPoint(raycaster, scene, space) {
+    // Sorted nearest-first by three, so the first hit is the one the user is looking at.
+    const [nearest] = raycaster.intersectObject(scene, true);
+    if (nearest)
+        return space.worldToPlan(nearest.point);
+    return planePoint(raycaster.ray, space);
+}
+/**
+ * Where a ray crosses the plan plane — the floor under the pointer, whatever is drawn above it.
+ *
+ * The fallback for a click that reached neither a handler nor any geometry at all: past the edge of
+ * the plan there is nothing to report but the ground the ray carries on to.
+ *
+ * Both the crossing and the fallback are taken through the scene's space, because R3F casts its rays
+ * in world coordinates and a scene fitted to the canvas draws a plan unit as some other number of
+ * those. Without it the reported position is the world one wearing plan units' name.
+ * @param ray - The ray the pointer cast, in world space.
+ * @param space - The scene's space.
+ * @returns The crossing, in plan units, or — for a ray running parallel to the plan, which crosses
+ *   it nowhere — where the ray started.
+ */
+export function planePoint(ray, space) {
+    return space.rayToPlan(ray) ?? space.worldToPlan(ray.origin);
+}
+/**
+ * Whether a press-and-release traveled far enough to be a drag rather than a click.
+ *
+ * R3F's `delta` is the pointer's travel since the press, rounded to whole pixels.
+ * @param event - The click event to judge.
+ * @returns Whether to treat it as a drag.
+ */
+function isDrag(event) {
+    return event.delta * event.delta > DRAG_SLOP_SQ_PX;
+}
+/**
+ * Squared pointer travel, in px², above which a release is a drag and not a click — so ~3.9 px of
+ * slop. Squared because that is how the imperative renderer's `dragThreshold` compared it, and this
+ * reproduces its feel exactly; a threshold in whole pixels would be four times looser.
+ */
+const DRAG_SLOP_SQ_PX = 15;
+/**
+ * Mesh-to-def resolution for every mounted container, keyed weakly by mesh identity — so nothing has
+ * to be cleaned up per renderer, and two renderers holding the same defs never collide.
+ */
+const resolvers = new WeakMap();

package/dist/external/ExternalCanvas.d.ts

@@ -0,0 +1,56 @@
+import { type ReactNode } from 'react';
+/**
+ * What a host that owns the canvas hands over — a MapLibre custom layer in practice. `Renderer`
+ * carries all three as optional props ({@link RendererProps} extends the partial of this), and
+ * `gl` arriving is what selects external mode, exactly as it selected the imperative renderer's.
+ */
+export interface ExternalCanvasProps {
+    /**
+     * The host's WebGL context. Rendering shares the host's context and canvas (`gl.canvas`) inside
+     * the host's own frame loop.
+     */
+    gl: WebGLRenderingContext | WebGL2RenderingContext;
+    /**
+     * Asks the host for a frame — `map.triggerRepaint()` under MapLibre. The demand loop's other
+     * half: the host owns every frame, so anything that would invalidate the renderer's own canvas —
+     * an `update()`, a texture upload, a re-layout backlog — asks the host instead.
+     */
+    requestFrame: () => void;
+    /**
+     * Subscribes the renderer's per-frame draw to the host's render hook. The host calls the
+     * subscribed function once per frame it draws — from a MapLibre custom layer's `render` — with
+     * its combined view-projection matrix, sixteen elements column-major.
+     * @param draw - Draws one frame with the host's matrix.
+     * @returns An unsubscribe function.
+     */
+    onFrame: (draw: (projectionMatrix: ArrayLike<number>) => void) => () => void;
+}
+/**
+ * `<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 declare function ExternalCanvas(props: ExternalCanvasProps & {
+    children?: ReactNode;
+}): null;
+//# sourceMappingURL=ExternalCanvas.d.ts.map