@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/events/pointer.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Picking: which def the pointer is on, and where on the plan.
+ *
+ * Two hooks are the way in — {@link usePointerProps} makes a layer's group interactive, and
+ * {@link usePickFilter} makes the canvas pick the way the renderer draws. Nothing outside this module
+ * calls anything else here; the rest is exported so the sibling spec can drive each piece on its own
+ * rather than through a mounted canvas.
+ */
+import { type RootState, 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';
+/**
+ * What picking asks of a mesh's owner, in the owner's own terms — instances and defs, never
+ * intersections. Pulling the instance out of an intersection is this module's work, because the
+ * intersection is three's; a container only answers about what it allocated.
+ *
+ * One interface rather than two registrations, because both answers have one owner and arrive at one
+ * moment. `SlotContainer` satisfies it as it stands, so a container registers itself.
+ */
+export interface HitSource {
+    /**
+     * The def a mesh instance belongs to, or `undefined` when none does — an instance released between
+     * the raycast and the dispatch, or a mesh whose picking is not implemented.
+     * @param instance - The instance the mesh reported.
+     * @returns The def.
+     */
+    defAt(instance: number | undefined): RenderableDef | undefined;
+    /**
+     * Where a def sits in this mesh's draw order, counted from the one drawn first.
+     * @param def - The def to place.
+     * @returns Its place in the draw order.
+     */
+    paintOrderOf(def: RenderableDef): number;
+}
+/** 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;
+/**
+ * Makes the canvas pick the way the renderer draws, for as long as the component is mounted.
+ *
+ * R3F's `events.filter` is the one hook into picking that sees the whole hit list, which is why both
+ * corrections live there: {@link occludeHits} drops what hidden geometry stands in front of, and
+ * {@link orderCoplanarHits} settles what the depth buffer never ordered. Both are the renderer's own
+ * reading of its scene, so the whole arrangement is here rather than at whichever component mounts
+ * it — a caller wires picking by calling this, and nothing outside this module has to know that there
+ * are two halves or which order they run in.
+ */
+export declare function usePickFilter(): void;
+/**
+ * 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 what speaks for a mesh's intersections, for as long as the mesh is mounted — so the
+ * dispatch and ordering paths stay free of per-mesh-type knowledge.
+ * @param mesh - The mesh whose hits the source speaks for.
+ * @param source - What answers for them.
+ * @returns An unregister function, safe to call after another source replaced this one.
+ */
+export declare function registerHitSource(mesh: Object3D, source: HitSource): () => void;
+/**
+ * The def an intersection hit.
+ *
+ * A mesh with no registered source 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;
+/**
+ * Drops the hits that geometry with no handlers hides, so a booth behind a wall or a model, opaque
+ * or translucent, is not picked. The first half of R3F's `events.filter`, which runs on its
+ * nearest-first hits; {@link orderCoplanarHits} is the second, over what survives.
+ *
+ * R3F raycasts only interactive layers, so it cannot see what stands in front of them. This casts
+ * the same ray at the whole scene and cuts the hits at the nearest object no interactive layer
+ * holds. A wall and a logo on a booth's roof differ only in distance: the logo lies on the roof, and
+ * the wall stands apart from it. So the cut keeps a hit up to {@link depthSeparation} behind the
+ * occluder, the least separation at which the depth buffer draws two surfaces in order. Nearer
+ * than that, the occluder is drawn on the hit, not in front of it. A click with every hit dropped is
+ * a miss, as a click on the occluder was before.
+ * @param hits - R3F's hits, nearest first.
+ * @param state - The root's state, holding the ray already aimed at the pointer.
+ * @param space - The scene's space, whose scale turns the plan-unit separation into a world one.
+ * @returns The hits in front of the nearest occluder.
+ */
+export declare function occludeHits(hits: Intersection[], state: RootState, space: Space): Intersection[];
+/**
+ * Reorders the hits the depth buffer never separated, so the one drawn last is picked first. R3F's
+ * `events.filter`, after {@link occludeHits} has cut away what is hidden.
+ *
+ * Three sorts its intersections by distance alone, and two coplanar polygons are not at two
+ * distances — they are at one distance the ray-triangle math resolves a little differently for each
+ * of them. Which one R3F dispatches first is that float noise, so a click on the overlap selects
+ * one shape on one frame and its neighbor on the next. Sorting stably does not help: the distances
+ * genuinely differ rather than tying, and the order three produced them in is a mesh's free list,
+ * which `SlotContainer` keeps deliberately apart from paint order.
+ *
+ * So the tie is settled by what the user is already looking at. Hits within
+ * {@link depthSeparation} of the nearest of their run are one depth, because that is the separation
+ * below which the depth buffer stops ordering surfaces and draw order alone decides what is on top
+ * — the same rule {@link occludeHits} cuts by. Within a run they are ordered by where they draw,
+ * last first, along the three keys three's own painter sort reads in the same order: the layer
+ * group they hang under, the batch's place in that layer, then the instance's place in the batch.
+ *
+ * A run is measured from its own first hit rather than from the hit before it, so a stack of
+ * surfaces each just inside the separation is still cut into runs instead of chaining into one.
+ * @param hits - R3F's hits, nearest first.
+ * @param space - The scene's space, whose scale turns the plan-unit separation into a world one.
+ * @returns The hits in pick order.
+ */
+export declare function orderCoplanarHits(hits: Intersection[], space: Space): Intersection[];
+/**
+ * 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,356 @@
+/**
+ * Picking: which def the pointer is on, and where on the plan.
+ *
+ * Two hooks are the way in — {@link usePointerProps} makes a layer's group interactive, and
+ * {@link usePickFilter} makes the canvas pick the way the renderer draws. Nothing outside this module
+ * calls anything else here; the rest is exported so the sibling spec can drive each piece on its own
+ * rather than through a mounted canvas.
+ */
+import { useThree } from '@react-three/fiber';
+import { useEffect } from 'react';
+import { depthSeparation } from '../space/clipping';
+import { useSpace } from '../space/Space';
+import { hotState } from '../utils/hot-state';
+/**
+ * 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,
+    };
+}
+/**
+ * Makes the canvas pick the way the renderer draws, for as long as the component is mounted.
+ *
+ * R3F's `events.filter` is the one hook into picking that sees the whole hit list, which is why both
+ * corrections live there: {@link occludeHits} drops what hidden geometry stands in front of, and
+ * {@link orderCoplanarHits} settles what the depth buffer never ordered. Both are the renderer's own
+ * reading of its scene, so the whole arrangement is here rather than at whichever component mounts
+ * it — a caller wires picking by calling this, and nothing outside this module has to know that there
+ * are two halves or which order they run in.
+ */
+export function usePickFilter() {
+    const setEvents = useThree((state) => state.setEvents);
+    // Picking is reported on the plan, and R3F casts its rays in world coordinates.
+    const space = useSpace();
+    useEffect(() => {
+        setEvents({
+            filter: (hits, state) => {
+                // Cut first, then order: dropping what is hidden cannot move the survivors along the ray,
+                // and ordering hits that were about to be dropped is work for nothing.
+                const visible = occludeHits(hits, state, space);
+                return orderCoplanarHits(visible, space);
+            },
+        });
+    }, [setEvents, space]);
+}
+/**
+ * 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 what speaks for a mesh's intersections, for as long as the mesh is mounted — so the
+ * dispatch and ordering paths stay free of per-mesh-type knowledge.
+ * @param mesh - The mesh whose hits the source speaks for.
+ * @param source - What answers for them.
+ * @returns An unregister function, safe to call after another source replaced this one.
+ */
+export function registerHitSource(mesh, source) {
+    sources.set(mesh, source);
+    return () => {
+        if (sources.get(mesh) === source)
+            sources.delete(mesh);
+    };
+}
+/**
+ * The def an intersection hit.
+ *
+ * A mesh with no registered source 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 sources.get(hit.object)?.defAt(hit.instanceId);
+}
+/**
+ * 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);
+}
+/**
+ * Drops the hits that geometry with no handlers hides, so a booth behind a wall or a model, opaque
+ * or translucent, is not picked. The first half of R3F's `events.filter`, which runs on its
+ * nearest-first hits; {@link orderCoplanarHits} is the second, over what survives.
+ *
+ * R3F raycasts only interactive layers, so it cannot see what stands in front of them. This casts
+ * the same ray at the whole scene and cuts the hits at the nearest object no interactive layer
+ * holds. A wall and a logo on a booth's roof differ only in distance: the logo lies on the roof, and
+ * the wall stands apart from it. So the cut keeps a hit up to {@link depthSeparation} behind the
+ * occluder, the least separation at which the depth buffer draws two surfaces in order. Nearer
+ * than that, the occluder is drawn on the hit, not in front of it. A click with every hit dropped is
+ * a miss, as a click on the occluder was before.
+ * @param hits - R3F's hits, nearest first.
+ * @param state - The root's state, holding the ray already aimed at the pointer.
+ * @param space - The scene's space, whose scale turns the plan-unit separation into a world one.
+ * @returns The hits in front of the nearest occluder.
+ */
+export function occludeHits(hits, state, space) {
+    if (hits.length === 0)
+        return hits;
+    const { interaction } = state.internal;
+    const occluder = state.raycaster
+        .intersectObject(state.scene, true)
+        .find((hit) => !isInteractive(hit.object, interaction));
+    if (!occluder)
+        return hits;
+    // Along the ray, a pitched view only lengthens the gap between two surfaces, never shortens it.
+    const cut = occluder.distance + depthSeparation(space.scale);
+    return hits.filter((hit) => hit.distance <= cut);
+}
+/**
+ * Reorders the hits the depth buffer never separated, so the one drawn last is picked first. R3F's
+ * `events.filter`, after {@link occludeHits} has cut away what is hidden.
+ *
+ * Three sorts its intersections by distance alone, and two coplanar polygons are not at two
+ * distances — they are at one distance the ray-triangle math resolves a little differently for each
+ * of them. Which one R3F dispatches first is that float noise, so a click on the overlap selects
+ * one shape on one frame and its neighbor on the next. Sorting stably does not help: the distances
+ * genuinely differ rather than tying, and the order three produced them in is a mesh's free list,
+ * which `SlotContainer` keeps deliberately apart from paint order.
+ *
+ * So the tie is settled by what the user is already looking at. Hits within
+ * {@link depthSeparation} of the nearest of their run are one depth, because that is the separation
+ * below which the depth buffer stops ordering surfaces and draw order alone decides what is on top
+ * — the same rule {@link occludeHits} cuts by. Within a run they are ordered by where they draw,
+ * last first, along the three keys three's own painter sort reads in the same order: the layer
+ * group they hang under, the batch's place in that layer, then the instance's place in the batch.
+ *
+ * A run is measured from its own first hit rather than from the hit before it, so a stack of
+ * surfaces each just inside the separation is still cut into runs instead of chaining into one.
+ * @param hits - R3F's hits, nearest first.
+ * @param space - The scene's space, whose scale turns the plan-unit separation into a world one.
+ * @returns The hits in pick order.
+ */
+export function orderCoplanarHits(hits, space) {
+    if (hits.length < 2)
+        return hits;
+    const separation = depthSeparation(space.scale);
+    const ordered = [];
+    for (let start = 0; start < hits.length;) {
+        let end = start + 1;
+        while (end < hits.length) {
+            const gap = hits[end].distance - hits[start].distance;
+            // A step *back* toward the camera ends the run rather than extending it. R3F sorts by event
+            // priority first and distance second, so a second root's hits follow the first root's as their
+            // own nearest-first list — two scenes, whose hits must not be ordered against each other
+            // however near the numbers land.
+            if (gap < 0 || gap > separation)
+                break;
+            end++;
+        }
+        const run = hits.slice(start, end);
+        // Reversed, so the hit drawn last comes first. `sort` is stable, so hits nothing here orders —
+        // a primitive whose picking is not implemented, two triangles of one instance — keep the
+        // nearest-first order three gave them rather than being shuffled by a comparator with nothing
+        // to say about them.
+        if (run.length > 1)
+            run.sort((a, b) => compareDrawOrder(b, a));
+        ordered.push(...run);
+        start = end;
+    }
+    return ordered;
+}
+/**
+ * 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;
+}
+/**
+ * Compares two hits by where they draw, earliest first.
+ *
+ * The three keys are three's own, read in three's order: a mesh inherits the `renderOrder` of its
+ * nearest ancestor group as its group order, which outranks its own `renderOrder`, which outranks
+ * anything within the mesh. Here that reads as the layer, then the batch, then the instance.
+ *
+ * **The layer is a key of its own because the two numberings are not one scale.** A layer's
+ * `<group>` carries its place in the whole tree's draw order, subdivided inside `[0, 2)`, while a
+ * batch mesh carries its kind's index among its layer's batches — `0`, `1`, `2`. So a batch is never
+ * comparable to a batch of another layer, and the mesh numbers alone would put the second batch of
+ * an early layer above the first batch of a late one. Collapsing them would mean giving every batch
+ * its layer's place plus a fraction, which is exactly the mantissa `Layer` keeps free for nesting.
+ *
+ * Three's own comparator is unreachable: `painterSortStable` is private to its WebGL renderer, and
+ * `renderer.renderLists` holds only the per-object answer — the instance key, the one this bug is
+ * about, exists nowhere in it.
+ *
+ * Two hits on one mesh share both object keys, and two hits on different meshes are nearly always
+ * separated by one of them, since a layer's place is unique in the tree and a batch's is unique in its
+ * layer. So the branches are exclusive in practice, which is also what keeps one mesh's places from
+ * ever being compared against another's — those count from zero independently and mean nothing
+ * against each other. Where two meshes do tie on both — the background quad draws level with the
+ * first layer, and three settles that by `material.id` — this reports nothing and the stable sort
+ * leaves them nearest-first.
+ * @param a - The first hit.
+ * @param b - The second hit.
+ * @returns Negative when `a` draws first, positive when `b` does, zero when nothing orders them.
+ */
+function compareDrawOrder(a, b) {
+    if (a.object !== b.object) {
+        return (groupOrderOf(a.object) - groupOrderOf(b.object) || a.object.renderOrder - b.object.renderOrder);
+    }
+    const source = sources.get(a.object);
+    if (!source)
+        return 0;
+    const first = source.defAt(a.instanceId);
+    const second = source.defAt(b.instanceId);
+    // A hit traced to no def reports the first place rather than the last: nothing is known about
+    // where it drew, and that must not outrank a def whose place is known.
+    return (first ? source.paintOrderOf(first) : 0) - (second ? source.paintOrderOf(second) : 0);
+}
+/**
+ * The group order three would give an object: the `renderOrder` of its nearest ancestor group,
+ * which for anything a layer holds is that layer's place in the tree's draw order.
+ * @param object - The object to place.
+ * @returns The group order, or `0` for an object under no group at all.
+ */
+function groupOrderOf(object) {
+    for (let node = object.parent; node; node = node.parent) {
+        if (node.isGroup)
+            return node.renderOrder;
+    }
+    return 0;
+}
+/**
+ * Whether an object sits in an interactive layer: it, or an ancestor, carries R3F handlers.
+ * @param object - The object hit.
+ * @param interaction - R3F's objects with handlers.
+ * @returns Whether R3F raycasts it for events.
+ */
+function isInteractive(object, interaction) {
+    for (let node = object; node; node = node.parent) {
+        if (interaction.includes(node))
+            return true;
+    }
+    return false;
+}
+/**
+ * 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;
+/**
+ * What speaks for each mounted container's mesh, keyed weakly by mesh identity — so nothing has to
+ * be cleaned up per renderer, and two renderers holding the same defs never collide.
+ *
+ * Kept across hot updates, because a container registers from a mount effect that a re-render does
+ * not re-run: a fresh map would leave every mesh in the scene unpickable until a full reload, which
+ * is what editing anything in this module's import graph used to do (see {@link hotState}).
+ */
+const sources = hotState(import.meta.hot, 'sources', () => 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