@solidrt/3d 0.0.67 → 0.0.68

package/AGENTS.md

@@ -91,7 +91,9 @@ Two layers. The imperative core is Solid-free: `createScene`,
 over the spatial core (`flux:spatial`, `alloy/src/spatial/`): every node
 in a scene has a core node, JS keeps the LOCAL position/quaternion/scale
 as the readable truth and forwards each write, and the core's flush
-(one call per microtask) recomputes only the moved subtrees and writes
+(one call per frame, in the publish pass of core's `onBeforeRender`
+ahead of the paint; at the microtask for a write made outside a frame)
+recomputes only the moved subtrees and writes
 each entry's uModel (plus uNormal for materials declaring it) and its
 visibility switch itself - a move costs its subtree, never the scene.
 ONE `setTargetParams` (the shared uViewProj + uCamPos) per camera
@@ -215,7 +217,10 @@ mesh: `frustumCulled: false` (Three's name; `setCulling`) for geometry
 a vertex stage moves beyond its box - a fullscreen quad, a custom
 displacement - and `cullMargin` (world units, Godot's
 `extra_cull_margin`) for bounded displacement such as wind. Sprites
-cull by their quad's reach at any facing. A SKINNED part is culled by
+cull by their quad's reach at any facing; a sprite whose material (or
+`params`) floors its screen size exceeds that reach far away, so the
+floor coming on switches the mesh's culling off, one way. A SKINNED
+part is culled by
 the union of its joints' boxes (the bake computes each joint's
 influence box in joint space, `ModelSkin.jointBounds`, .sol3m VERSION
 5; the joint nodes carry them as culling-only bounds, outside the
@@ -399,7 +404,8 @@ unmount lets them go in; nearest declaring ancestor wins) and cascades
 nothing unless they declare `from`/`exit` -
 a squad of instances spawning in is one `stagger` on their group, and
 for the nodes straight under the scene root it is `<Scene stagger>` /
-`createScene({ stagger })` (a declaration on `scene.root`). A populated
+`createScene({ stagger })` / `scene.setStagger(ms)` (a declaration on
+`scene.root`). A populated
 mesh unmounts as `destroy(mesh)` then `disposeInstances(mesh)`, and the
 dispose waits for a mesh still animating out, so an `<Instance>`'s exit
 plays through its `<InstancedMesh>`'s unmount (`model.dispose` waits the
@@ -987,7 +993,15 @@ box's twelve triangles, so its hits carry the struck face's `normal` and
 no `face`/`uv` - and a ray from inside it meets the far side, the
 surface contract overlap/sweep share. Both methods
 flush pending writes first (the lookAt/project immediacy contract), and
-both skip invisible meshes.
+both skip invisible meshes. A sprite under a screen-size clamp
+(`sprite({ minScreenPx, maxScreenPx })`) draws at a size the index does
+not know - the vertex stage scales it by the pixels per unit at its
+depth under the camera drawing it - so `pick` (which has a camera; a
+view's pick its own) replaces the ray's hits on clamped sprites with an
+exact ray-quad test at the drawn size, the quad rebuilt as the stage
+builds it (camera right/up, or a fixed-y sprite's yaw basis), hits
+carrying the plane distance and a normal facing the ray. `raycast` is a
+world query and keeps the index's unit-box answer.
 
 ### Collision
 
@@ -1312,7 +1326,7 @@ opts out of the scene's fog (all four library materials take it).
 #### sprite
 
 `sprite({ color?, map?, transparent?, blend?, billboard?, shape?,
-falloff? })` - unlit on a quad
+falloff?, minScreenPx?, maxScreenPx? })` - unlit on a quad
 that turns to face the camera IN THE VERTEX STAGE (off the shared
 uCamRight/uCamUp, or uCamPos for `billboard: "fixed-y"`, which yaws
 only and stays upright on world y - Godot's BILLBOARD_FIXED_Y, the
@@ -1326,7 +1340,18 @@ facing), so hits carry no normal/face/uv. `shape: "radial"` is a
 procedural falloff over the quad's inscribed disc, `(1 - 2|uv -
 0.5|)^falloff` (default 1; 2 a soft puff) multiplying color and alpha,
 so a glow, flare or puff needs no texture; it composes with a `map`
-and with `blend: "add"`. `examples/sprites.tsx`.
+and with `blend: "add"`. `minScreenPx`/`maxScreenPx` clamp the quad's
+smaller axis on SCREEN (pixels; 0 = off), scaled uniformly about its
+center in the vertex stage by the pixels one world unit covers at the
+quad's depth (depth alone, from the shared uniforms, so perspective
+and orthographic alike): a floor is the marker that stays findable at
+distance, a ceiling the label that must not balloon, equal bounds a
+constant screen size (Three's `sizeAttenuation: false`, `scale` then
+the aspect alone). The clamp is core's `screenSizeScale`, shared with
+@solidrt/2d's sprites; the per-entry `uScreenPx`, so a per-mesh
+`params` can override it. `scene.pick`/`view.pick` test the drawn
+quad (below), and a floored sprite's mesh turns its frustum culling
+off (one way; `setCulling` turns it back on). `examples/sprites.tsx`.
 
 #### shaderMaterial
 
@@ -1398,10 +1423,14 @@ vertex stream stepped per instance: on the mesh it is an `InstanceStream`
 (the layout, a byte mirror, a mesh-owned GPU buffer), written through
 `instanceAttribute(mesh, name)` - the accessor `geometryAttribute`
 returns, record index in, values as the shader sees them, the codec
-packing the bytes - and published with `updateRecords(mesh, { stream?,
-first?, count? })`, which is `updateVertices` for records: one coalesced
-buffer write per dirty stream at the scene's sync, so ten moved records
-of ten thousand cost ten. Its meshes come from `createInstancedMesh`
+packing the bytes - or in bulk through the mirror itself, `records(mesh,
+stream?)` (a Float32Array over an all-float layout, bytes otherwise;
+read it at use time, growth replaces it), and published with
+`updateRecords(mesh, { stream?, first?, count? })`, which is
+`updateVertices` for records: one coalesced buffer write per dirty
+stream at the scene's sync, so ten moved records of ten thousand cost
+ten - the same `records`/`updateRecords` pair as @solidrt/2d's records
+layer. Its meshes come from `createInstancedMesh`
 (the first buffer is the core-written matrix, the rest are streams; the
 second is the STYLE record, below) or `createRecordMesh` (every buffer a
 stream); a `createMesh` mesh is rejected at add(). `instanceStyle: [..]`
@@ -1519,11 +1548,13 @@ through `instanceAttribute`. `count` picks how many draw (default all).
 `setRecords(mesh, records, count?)` rewrites from the start (count
 defaults to the records written; more than capacity GROWS: capacity
 doubles into replacement buffers, the entry is re-pointed via
-`setDrawBuffers`, the old ones are freed), `instanceAttribute` +
-`updateRecords(mesh, { first, count })` rewrites a few (the range is
-against capacity, so write ahead and dial after), and
-`setRecordCount(mesh, n)` is the population dial (clamped to capacity;
-frame-rate-safe). Records are opaque data (position/yaw/tint/whatever
+`setDrawBuffers`, the old ones are freed), `records(mesh)` (the mirror)
+or `instanceAttribute` + `updateRecords(mesh, { first, count })`
+rewrites a few (the range is against capacity, so write ahead and dial
+after), and `setRecordCount(mesh, n)` is the population dial (clamped to
+capacity; frame-rate-safe). The @solidrt/2d records layer speaks the
+same three verbs over its sprites, `setRecords` alone staying the
+mesh's (a layer's population is addSprite's). Records are opaque data (position/yaw/tint/whatever
 your shader reads), so the
 library cannot know where they place instances: a record mesh has NO
 picking leaf unless you pass `bounds` (local, covering the population) -
@@ -3014,8 +3045,9 @@ successors) as ordinary content, the model-loading split repeated:
   meshes skip uModel writes; the fresh matrix is
   written on unhide. A freshly attached entry starts off the same way and
   the core's flush turns it on when it writes uModel - never add one
-  live: it has no world matrix yet, and drawn before the sync microtask it
-  flashes at the world origin for a frame.
+  live: it has no world matrix yet, and drawn before the sync (which runs
+  ahead of the paint for a write made in a frame, at the microtask
+  otherwise) it would flash at the world origin for a frame.
 - Instancing pairs strictly at add(), like layout: an instanced material
   needs a createInstancedMesh or createRecordMesh mesh and vice versa,
   and every instance buffer the material declares must be a layout the
@@ -3039,8 +3071,14 @@ successors) as ordinary content, the model-loading split repeated:
   `data` and the scene's sync publishes the `dirty` range (`updateRecords`
   marks it for accessor writes) - so a write on a mesh outside any scene
   shows once it is added (the dirty range waits), and reading the GPU
-  buffer back mid-frame can lag the mirror by one sync. Growth replaces
-  `data`: hold the accessor, not the view.
+  buffer back between the write and the sync lags the mirror. The sync
+  runs in the publish pass of core's `onBeforeRender`, ahead of the
+  frame's paint (at the microtask for a write made outside a frame), so
+  a `setRecords` made in onFrame is in that frame's picture with its
+  count, its buffers and its bytes together - the count alone
+  (`setRecordCount`) reaches the engine at once. Growth replaces
+  `data`: hold the accessor, or re-read `records(mesh)` at use time,
+  never a hoisted view.
 - The sugar is for FEW records, the mirror is for MANY. `setInstanceStyle`
   over an all-float layout is indexed stores; over a packed layout (the
   stock `float16x4` color included) it is a codec call per component,
@@ -3050,10 +3088,11 @@ successors) as ordinary content, the model-loading split repeated:
   color, 9 ms through the accessor, 5 ms through the mirror - and that
   5 ms is the app's own per-instance tint math, the write itself is
   free. A population restyled per frame writes the mirror in bulk:
-  a typed view over `stream.data` (a Float32Array as handed out, a
-  `Float16Array` over the stock color, indexed by slot times components)
-  filled in a plain loop, then ONE `updateRecords(mesh, { first, count
-  })` - zero per-component calls, the same shape as `setRecords`.
+  `records(mesh)` (a Float32Array over an all-float layout, bytes
+  otherwise - a `Float16Array` over the stock color, indexed by slot
+  times components) filled in a plain loop, then ONE `updateRecords(mesh,
+  { first, count })` - zero per-component calls, the same shape as
+  `setRecords`.
 - Instanced casters: `castShadow` on a populated mesh needs a depth pass
   with the instance placement in it - the stock materials' `instanced`
   carries one, a custom class needs `shadowVertex` (see shadows below);

package/README.md

@@ -60,9 +60,12 @@ drag, and hover enter/leave pairs - hit testing runs over a BVH the
 scene maintains incrementally, so events put no ceiling on scene size.
 Underneath sit `scene.pick(x, y)` (the camera ray through a pixel,
 `project()`'s inverse) and `scene.raycast(origin, direction)`; hits are
-bounding-box accurate in v1. A scene also takes a `background` - fragment
-GLSL drawn inside its own pass behind the meshes, replacing the stacked
-backdrop-texture pattern.
+per triangle, carrying the face, its uv and a normal facing the ray.
+`scene.overlap`, `scene.sweep` and `scene.moveAndSlide` ask the same
+index what a volume touches, where a moving one first touches, and how a
+character body slides through it. A scene also takes a `background` -
+fragment GLSL drawn inside its own pass behind the meshes, or a skybox
+cube - replacing the stacked backdrop-texture pattern.
 Custom materials get a standard uniform set - per-mesh `uModel`/`uNormal`,
 shared `uViewProj`/`uCamPos`/`uCamRight`/`uCamUp`, each written once per
 change - plus your own uniforms: scene-wide via `scene.setParams` (one write
@@ -83,27 +86,27 @@ every fleet only JS can step (`examples/instanced.tsx`). And
 blinn, fresnel, a standard vertex stage) to compose your own lit looks
 from plain template literals.
 
-v1 scope: unlit color/textured materials plus `shaderMaterial` (your own
-GLSL as a first-class material), sprites (`<Sprite>` with a `sprite()`
-material: a quad facing the camera in the vertex stage, full or fixed-y
-billboarding), geometry generators (box, plane, circle,
-ring, sphere, cylinder, cone, torus, torus knot, the platonic solids with
-`detail` subdivision, so the icosahedron is also the icosphere), a profile
-kit for custom
-solids (`extrude` with bevels, `lathe`, polyline `sweep`/`tube` with
-mitred joints, flat `shape`, with `fillet`/`roundRect`/`triangulate`
-helpers), geometry as data (`transformGeometry` bakes a placement into
-vertices and `mergeGeometries` concatenates parts, so a static scene is
-one mesh per material), open vertex layouts (`withAttribute` appends any
-named channel to a geometry's interleave, `withColors` is the `aColor`
-vec4 case - tint, baked AO, any four scalars - and materials read channels
-by name), one perspective camera
-with an orbit control (`<OrbitCamera>` as a Scene child, or
-`createOrbitCamera` imperatively; drag, pinch/wheel zoom and a pad reach
-it through an input map the app binds, auto-orbit),
-mesh picking with pointer events, scene backgrounds, transparency, and
-lights (`lit` material with hemisphere ambient, up to four directional
-light nodes, Blinn-Phong highlight and triplanar mapping).
-Model loading and shadows are staged next - see `okf/notes/3d-roadmap.md`
-for the ranked list. Full usage notes and traps: [AGENTS.md](AGENTS.md);
-runnable examples: [examples/](examples/).
+In the package: materials (`unlit`, Blinn-Phong `phong`, metal/rough
+`standard` with surface maps and image-based lighting, `sprite` for
+camera-facing quads with a screen-size clamp, and `shaderMaterial` for
+your own GLSL as a first-class material), lights as graph nodes
+(directional, spot, point and hemisphere, up to eight, with cascaded
+directional, spot and six-face point shadows), geometry generators (box,
+plane, circle, ring, sphere, capsule, cylinder, cone, torus, torus knot,
+the platonic solids with `detail` subdivision, so the icosahedron is also
+the icosphere), a profile kit for custom solids (`extrude` with bevels,
+`lathe`, polyline `sweep`/`tube` with mitred joints, flat `polygon`, with
+`fillet`/`roundRect`/`triangulate` helpers), geometry as data
+(`transformGeometry` bakes a placement into vertices, `mergeGeometries`
+concatenates parts, `withAttribute`/`withColors` append named channels
+materials read by name, morph targets), models (`loadGltf`/`loadModel`,
+skins, a clip mixer with root motion, a baked `.sol3m` container with
+compressed textures), Gaussian splats, level of detail, views of one
+scene (split screen, a minimap, a reflection probe), environment and sky
+(skybox, equirect panoramas, baked environments, fog, bloom, tone
+mapping), camera controls (`<OrbitCamera>` and `<FirstPersonCamera>`
+driven by an input map the app binds, shots and blends between them),
+picking with pointer events, and the collision queries. Full usage notes
+and traps: [AGENTS.md](AGENTS.md); runnable examples:
+[examples/](examples/); the ranked list of what is next:
+`okf/notes/3d-roadmap.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -20,10 +20,10 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/test": "0.0.67"
+    "@solidrt/test": "0.0.68"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.13",
-    "@solidrt/core": "0.0.67"
+    "@solidrt/core": "0.0.68"
   }
 }

package/src/components/group.tsx

@@ -2,11 +2,11 @@ import { onCleanup, untrack, useContext } from "@solidrt/core"
 import type { ParentComponent } from "@solidrt/core"
 import { SceneContext, provide } from "./context.tsx"
 import { syncNode } from "./node-props.ts"
-import type { TransformProps, BubblingPointerEventProps } from "./node-props.ts"
+import type { TransformProps, BubblingNodePointerProps } from "./node-props.ts"
 import { add, createGroup, destroy } from "../node.ts"
 import type { SceneNode } from "../node.ts"
 
-export type GroupProps = TransformProps & BubblingPointerEventProps & { ref?: (node: SceneNode) => void }
+export type GroupProps = TransformProps & BubblingNodePointerProps & { ref?: (node: SceneNode) => void }
 
 /** A transform node: children inherit its position/rotation/scale. Its
  * pointer events are the ones bubbling up from a hit descendant; a group

package/src/components/index.ts

@@ -16,7 +16,7 @@
 
 export { useScene } from "./context.tsx"
 export type { CameraTarget } from "./context.tsx"
-export type { BubblingPointerEventProps, PointerEventProps, TransformProps } from "./node-props.ts"
+export type { BubblingNodePointerProps, NodePointerProps, TransformProps } from "./node-props.ts"
 export { Scene } from "./scene.tsx"
 export type { ScenePointerProps, SceneProps } from "./scene.tsx"
 export { View3d } from "./view3d.tsx"

package/src/components/instanced-mesh.tsx

@@ -2,7 +2,7 @@ import { createContext, createEffect, onCleanup, untrack, useContext } from "@so
 import type { ParentComponent } from "@solidrt/core"
 import { SceneContext, provide } from "./context.tsx"
 import { syncNode } from "./node-props.ts"
-import type { TransformProps, PointerEventProps } from "./node-props.ts"
+import type { TransformProps, NodePointerProps } from "./node-props.ts"
 import { syncMesh } from "./mesh.tsx"
 import type { PopulatedMeshProps } from "./mesh.tsx"
 import { add, destroy, setMorphWeights } from "../node.ts"
@@ -92,7 +92,7 @@ export let InstancedMesh: ParentComponent<InstancedMeshProps> = props => {
   )
 }
 
-export type InstanceProps = TransformProps & PointerEventProps & {
+export type InstanceProps = TransformProps & NodePointerProps & {
   /** The instance's style record (setInstanceStyle as a prop): one value
    * per component of the material's second instance buffer, in order -
    * `[r, g, b, a]` under a stock material's `instanceColors`. Reactive;

package/src/components/lod.tsx

@@ -3,7 +3,7 @@ import type { ParentComponent } from "@solidrt/core"
 import { LodContext, SceneContext, provide } from "./context.tsx"
 import type { LodRegistry } from "./context.tsx"
 import { syncNode } from "./node-props.ts"
-import type { TransformProps, BubblingPointerEventProps } from "./node-props.ts"
+import type { TransformProps, BubblingNodePointerProps } from "./node-props.ts"
 import { syncMesh } from "./mesh.tsx"
 import type { PopulatedMeshProps } from "./mesh.tsx"
 import { InstancedMeshContext } from "./instanced-mesh.tsx"
@@ -15,7 +15,7 @@ import { disposeInstances, setCastShadow } from "../mesh.ts"
 import type { InstancedMesh as InstancedMeshNode } from "../mesh.ts"
 
 export type LodProps = TransformProps &
-  BubblingPointerEventProps & {
+  BubblingNodePointerProps & {
     /** The cross-fade band fraction (createLod's `fade`); default 0. */
     fade?: number
     ref?: (node: SceneNode) => void

package/src/components/mesh.tsx

@@ -2,7 +2,7 @@ import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
 import type { VoidComponent } from "@solidrt/core"
 import { SceneContext } from "./context.tsx"
 import { syncNode } from "./node-props.ts"
-import type { TransformProps, PointerEventProps } from "./node-props.ts"
+import type { TransformProps, NodePointerProps } from "./node-props.ts"
 import { add, destroy, setMorphWeights } from "../node.ts"
 import type { MorphWeights } from "../node.ts"
 import { createMesh, setCastShadow, setCulling, setEnvironment, setGeometry, setLayers, setMaterial, setMeshParams, setRenderOrder } from "../mesh.ts"
@@ -12,7 +12,7 @@ import type { ShaderParams } from "@solidrt/core/gpu"
 import type { Geometry } from "../geometry.ts"
 import type { Material } from "../material.ts"
 
-export type MeshProps = TransformProps & PointerEventProps & {
+export type MeshProps = TransformProps & NodePointerProps & {
   geometry: Geometry
   material: Material
   /** Per-mesh uniforms for a custom material (setMeshParams as a prop).

package/src/components/node-props.ts

@@ -1,7 +1,7 @@
 import { createEffect, onCleanup, useContext } from "@solidrt/core"
 import { LodContext } from "./context.tsx"
 import { setTransform, setTransition, setVisible } from "../node.ts"
-import type { NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneNode, TransitionEndEvent } from "../node.ts"
+import type { HoverHandlers, NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneNode, TransitionEndEvent } from "../node.ts"
 import type { NodeTransition } from "flux:spatial"
 import type { Quat, Vec3 } from "../math.ts"
 
@@ -36,7 +36,7 @@ export type TransformProps = {
  * the built-in <Scene> leaf does (opt out with events={false}); an `output`
  * leaf spreads them itself.
  */
-export type PointerEventProps = BubblingPointerEventProps & {
+export type NodePointerProps = BubblingNodePointerProps & {
   /** Hover: enter/leave pair on the struck node alone, so only a hit
    * target - a mesh or an instance - takes them; `<Group>` and `<Lod>`
    * bubble and omit the pair. */
@@ -46,7 +46,7 @@ export type PointerEventProps = BubblingPointerEventProps & {
 
 /** The pointer props every node takes: the events that bubble from the
  * hit up through the Groups above it, without the hover pair. */
-export type BubblingPointerEventProps = {
+export type BubblingNodePointerProps = {
   onPointerDown?: (event: NodePointerEvent) => void
   onPointerMove?: (event: NodePointerEvent) => void
   onPointerUp?: (event: NodePointerEvent) => void
@@ -60,7 +60,7 @@ export type BubblingPointerEventProps = {
   onTap?: (event: NodeTapEvent) => void
 }
 
-export function syncNode(node: SceneNode, props: TransformProps & PointerEventProps): void {
+export function syncNode(node: SceneNode & HoverHandlers, props: TransformProps & NodePointerProps): void {
   // One effect for the transform and the handlers: re-assigning eight
   // handler fields on a transform write is free, an effect of its own is
   // not (a node component's mount cost is mostly its effects and its

package/src/components/scene.tsx

@@ -63,7 +63,7 @@ export type SceneProps = ScenePointerProps & {
   /** Stagger (ms) for the nodes straight under the scene root: their
    * enters and exits beginning in one frame are spaced by `index *
    * stagger`, the whole-scene form of `<Group transition={{ stagger }}>`
-   * (see SceneOptions.stagger). Set at creation. */
+   * (see SceneOptions.stagger). Live (scene.setStagger). */
   stagger?: number
   /** Scene-wide fog (scene.setFog): linear `{ color, near, far }` or exp2
    * `{ color, density }`, optionally thinning above `height` by
@@ -256,6 +256,11 @@ export let Scene: ParentComponent<SceneProps> = props => {
     l => scene.setLayers(l ?? 1),
     { defer: true },
   )
+  createEffect(
+    () => props.stagger,
+    ms => scene.setStagger(ms ?? null),
+    { defer: true },
+  )
   untrack(() => props.ref)?.(scene)
   // The pointer feed the app handed in listens at the scene's root, and
   // children reach it through useScene().pointer. Fixed at creation, like

package/src/components/sprite.tsx

@@ -1,7 +1,7 @@
 import { onCleanup, untrack, useContext } from "@solidrt/core"
 import type { VoidComponent } from "@solidrt/core"
 import { SceneContext } from "./context.tsx"
-import type { TransformProps, PointerEventProps } from "./node-props.ts"
+import type { TransformProps, NodePointerProps } from "./node-props.ts"
 import { syncMesh } from "./mesh.tsx"
 import { add, destroy } from "../node.ts"
 import { createSprite } from "../mesh.ts"
@@ -9,7 +9,7 @@ import type { Mesh as MeshNode } from "../mesh.ts"
 import type { ShaderParams } from "@solidrt/core/gpu"
 import type { Material } from "../material.ts"
 
-export type SpriteProps = TransformProps & PointerEventProps & {
+export type SpriteProps = TransformProps & NodePointerProps & {
   /** A `sprite()` material (any material draws, only a sprite one turns). */
   material: Material
   /** Per-mesh uniforms, merge semantics - as on Mesh. */

package/src/first-person.ts

@@ -29,7 +29,9 @@
 //
 // Pose is plain mutable state; a nudge or a verb pushes it at once (a
 // mouse move under lock needs no frame loop), and update(dt) integrates
-// the rates and the glide from the app's own onFrame. Only `active` is
+// the rates and the glide from the app's own onFrame (onBeforeRender when
+// the camera rides something the frame moves, so it sees the frame's
+// final pose). Only `active` is
 // reactive: the frame-loop gate, true while any rate reads non-zero (a
 // held key, a deflected stick) or a glide is in flight, so a still scene
 // renders nothing new. update() returns whether the pose changed since

package/src/index.ts

@@ -6,8 +6,8 @@
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
 export { add, createGroup, destroy, getMorphNames, getMorphWeights, getRotation, getTransform, lookAt, remove, setMorphWeights, setTransform, setTransition, setVisible, worldPosition } from "./node.ts"
-export type { LodConfig, MorphWeights, NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneEventBase, SceneNode, ScenePointerEvent, ScenePointerListener, SceneTapEvent, SceneWheelEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
-export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, setCastShadow, setCulling, setDrawRange, setEnvironment, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, instanceAttribute, updateRecords, INSTANCE_FLOATS } from "./mesh.ts"
+export type { HoverHandlers, LodConfig, MorphWeights, NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneEventBase, SceneNode, ScenePointerEvent, ScenePointerListener, SceneTapEvent, SceneWheelEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
+export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, setCastShadow, setCulling, setDrawRange, setEnvironment, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, instanceAttribute, records, updateRecords, INSTANCE_FLOATS } from "./mesh.ts"
 export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceOrderOptions, InstanceSlots, InstanceStream, Mesh as MeshNode, MeshInstances, RecordMesh as RecordMeshNode, RecordMeshOptions, UpdateRecordsOptions } from "./mesh.ts"
 export { createDirectionalLight, createHemisphereLight, createPointLight, createSpotLight, setLight } from "./light.ts"
 // The shader-source caps, also on the /glsl subpath next to the sources they size.
@@ -62,8 +62,8 @@ export type {
   MeshProps,
   OrbitCameraProps,
   PerspectiveCameraProps,
-  PointerEventProps,
-  BubblingPointerEventProps,
+  NodePointerProps,
+  BubblingNodePointerProps,
   GroupProps,
   PointLightProps,
   RecordMeshProps,

package/src/material.ts

@@ -20,6 +20,7 @@
 // @solidrt/core/gpu) stays first-class beneath both.
 
 import {
+  checkScreenSize,
   compileShader,
   createRenderPipeline,
   destroyProgram,
@@ -28,6 +29,7 @@ import {
   glsl,
   linkProgram,
   programAttributes,
+  SCREEN_SIZE_GLSL,
 } from "@solidrt/core/gpu"
 import type {
   BlendMode,
@@ -97,6 +99,10 @@ export type Material = {
    * like them, so the solids fill the depth before the fragments that
    * cannot early-z. */
   cutout?: boolean
+  /** How a `sprite()` material's quad faces the camera (set by sprite()):
+   * what the scene's pick rebuilds to test a screen-size-clamped sprite
+   * at its drawn size. Absent on every other material. */
+  billboard?: "full" | "fixed-y"
   /** The instance buffers, when the material's pipeline declares them
    * (shaderMaterialClass's `instanceBuffers`; the stock materials'
    * `instanced`), one layout per buffer after the geometry's. Such a
@@ -945,6 +951,27 @@ export type SpriteOptions = Omit<UnlitOptions, "instanced" | "instanceColors" |
    * soft puff, 0.5 a hard-edged disc), the per-entry `uFalloff`. Needs
    * `shape`. */
   falloff?: number
+  /**
+   * The screen-size clamp's floor, pixels (default 0: off): however far
+   * the camera is, the quad draws at least this big on its smaller axis,
+   * scaled uniformly about its center so its aspect holds - a marker or
+   * handle that stays findable at distance. The vertex stage scales by
+   * the pixels one world unit covers at the quad's depth (the depth
+   * alone, no foreshortening), so it is right under perspective and
+   * orthographic cameras alike, and `pick` tests the drawn quad. The
+   * per-entry `uScreenPx.x`; a per-mesh `params` may override the pair.
+   * A floored sprite's mesh turns its frustum culling off (its quad can
+   * exceed its box far away). Finite, >= 0.
+   */
+  minScreenPx?: number
+  /**
+   * The clamp's ceiling, pixels (default 0: off): the quad draws at most
+   * this big on its smaller axis however close the camera comes. Equal
+   * to `minScreenPx` it is a constant screen size, Three's
+   * `sizeAttenuation: false`, and `scale` then carries the aspect alone.
+   * The per-entry `uScreenPx.y`. Never below a floor that is on.
+   */
+  maxScreenPx?: number
 }
 
 // The radial shape as a tier-2 surface on the unlit fragment: the
@@ -962,11 +989,29 @@ const RADIAL_SURFACE = glsl`
 
 // The billboard vertex stages: the unit quad's corners placed along the
 // camera axes at the mesh's world position, with the quad's size read
-// off uModel's column lengths so `scale` sizes the sprite like any mesh.
-// The rotation part of uModel is otherwise ignored (the camera decides
-// the facing). Fixed-y takes the yaw from the camera-to-center direction
-// flattened onto XZ; straight above or below there is no yaw to take, so
-// the quad falls back to facing +z rather than dividing by zero.
+// off uModel's column lengths so `scale` sizes the sprite like any mesh,
+// then clamped on screen (core's screenSizeScale over uScreenPx, the
+// material's minScreenPx/maxScreenPx; identity at [0, 0]). The rotation
+// part of uModel is otherwise ignored (the camera decides the facing).
+// Fixed-y takes the yaw from the camera-to-center direction flattened
+// onto XZ; straight above or below there is no yaw to take, so the quad
+// falls back to facing +z rather than dividing by zero. The scene's pick
+// rebuilds exactly this quad for a clamped sprite (scene.ts
+// clampedSpriteHit); the two must agree.
+//
+// The pixels one world unit covers at the quad's depth: the center and
+// the center one camera-up unit away, projected, are half a viewport
+// height apart per NDC unit. Depth alone, no foreshortening, from the
+// shared uniforms only, and the same under an orthographic camera (clip
+// w is 1 there).
+const SPRITE_PX_PER_UNIT = glsl`
+  float spritePxPerUnit(vec3 center) {
+    vec4 c = uViewProj * vec4(center, 1.0);
+    vec4 u = uViewProj * vec4(center + uCamUp, 1.0);
+    return abs(u.y / u.w - c.y / c.w) * 0.5 * uViewport.y;
+  }
+`
+
 const SPRITE_VERTEX_SRC = glsl`
   in vec3 aPos;
   in vec2 aUV;
@@ -976,10 +1021,15 @@ const SPRITE_VERTEX_SRC = glsl`
   uniform mat4 uViewProj;
   uniform vec3 uCamRight;
   uniform vec3 uCamUp;
+  uniform vec2 uViewport;
+  uniform vec2 uScreenPx;
+  ${SCREEN_SIZE_GLSL}
+  ${SPRITE_PX_PER_UNIT}
 
   void main() {
     vec3 center = uModel[3].xyz;
     vec2 size = vec2(length(uModel[0].xyz), length(uModel[1].xyz));
+    size *= screenSizeScale(size, spritePxPerUnit(center), uScreenPx);
     vec3 world = center + uCamRight * (aPos.x * size.x) + uCamUp * (aPos.y * size.y);
     vWorldPos = world;
     gl_Position = uViewProj * vec4(world, 1.0);
@@ -995,10 +1045,16 @@ const SPRITE_FIXED_Y_VERTEX_SRC = glsl`
   uniform mat4 uModel;
   uniform mat4 uViewProj;
   uniform vec3 uCamPos;
+  uniform vec3 uCamUp;
+  uniform vec2 uViewport;
+  uniform vec2 uScreenPx;
+  ${SCREEN_SIZE_GLSL}
+  ${SPRITE_PX_PER_UNIT}
 
   void main() {
     vec3 center = uModel[3].xyz;
     vec2 size = vec2(length(uModel[0].xyz), length(uModel[1].xyz));
+    size *= screenSizeScale(size, spritePxPerUnit(center), uScreenPx);
     vec3 toCam = uCamPos - center;
     toCam.y = 0.0;
     float len = length(toCam);
@@ -1021,6 +1077,11 @@ let spriteClasses = new Map<string, ShaderMaterialClass>()
  * plane. Unlike unlit, `transparent` defaults to TRUE - sprites are cutouts
  * far more often than not (Three's SpriteMaterial default) - pass false
  * for an opaque one. Culling is off: a camera-facing quad has no back.
+ * `minScreenPx`/`maxScreenPx` clamp the quad's size on screen (the
+ * per-entry uScreenPx, so sprites sharing the material share the clamp
+ * and one draw; a per-mesh `params` override takes a mesh its own); the
+ * scene's pick tests the drawn quad, and a floored sprite's mesh is never
+ * frustum-culled.
  */
 export function sprite(opts: SpriteOptions = {}): Material {
   // Excluded by the type and checked for a JS caller: the billboard stage
@@ -1039,6 +1100,9 @@ export function sprite(opts: SpriteOptions = {}): Material {
   if (opts.shape !== undefined && !radial) throw new Error('sprite: shape must be "radial", got ' + opts.shape)
   if (opts.falloff !== undefined && !radial) throw new Error("sprite: falloff needs shape")
   if (opts.falloff !== undefined && !(Number.isFinite(opts.falloff) && opts.falloff > 0)) throw new Error("sprite: falloff must be a positive number, got " + opts.falloff)
+  let minScreenPx = opts.minScreenPx ?? 0
+  let maxScreenPx = opts.maxScreenPx ?? 0
+  checkScreenSize("sprite", minScreenPx, maxScreenPx)
   let key = [map, transparent, blend, fixedY, fog, radial].join("|")
   let cls = spriteClasses.get(key)
   if (cls === undefined) {
@@ -1058,9 +1122,11 @@ export function sprite(opts: SpriteOptions = {}): Material {
     })
     spriteClasses.set(key, cls)
   }
-  let params: ShaderParams = { uColor }
+  let params: ShaderParams = { uColor, uScreenPx: [minScreenPx, maxScreenPx] }
   if (radial) params.uFalloff = opts.falloff ?? 1
-  return cls.instance({ params, textures: map ? { uMap: opts.map! } : undefined })
+  let material = cls.instance({ params, textures: map ? { uMap: opts.map! } : undefined })
+  material.billboard = fixedY ? "fixed-y" : "full"
+  return material
 }
 
 /** The attributes `material` reads that `layout` does not carry (name and

package/src/mesh.ts

@@ -15,9 +15,9 @@ import type { Material } from "./material.ts"
 import type { TransformUpdate } from "./math.ts"
 import * as spatial from "flux:spatial"
 import { activateMorph, afterFree, createWeightsTexture, enterScene, leaveScene, makeNode, rebindMorph, remove, resetMorph, setTransform } from "./node.ts"
-import type { SceneNode } from "./node.ts"
+import type { HoverHandlers, SceneNode } from "./node.ts"
 
-export type Mesh = SceneNode & {
+export type Mesh = SceneNode & HoverHandlers & {
   kind: "mesh"
   geometry: Geometry
   material: Material
@@ -176,9 +176,10 @@ export type InstanceSlots = { slots: (InstanceNode | null)[]; free: number[] }
  * attribute list the material declared for it (any vertex format,
  * tightly packed), `data` the JS mirror of `capacity` records - a
  * Float32Array over an all-float layout, a Uint8Array otherwise
- * (vertexView's rule) - and `buffer` the mesh-owned GPU copy. Writes go
- * through instanceAttribute's accessor (or setInstanceStyle / setRecords,
- * which encode for you), land in the mirror, and publish as ONE
+ * (vertexView's rule; `records(mesh, stream)` hands it out for bulk
+ * writes) - and `buffer` the mesh-owned GPU copy. Writes go through
+ * instanceAttribute's accessor (or setInstanceStyle / setRecords, which
+ * encode for you) or the mirror itself, land in the mirror, and publish as ONE
  * coalesced buffer write per stream at the scene's next sync over the
  * `dirty` byte range - a frame-rate path, like setTransform. Growth
  * replaces `data` and `buffer` (the accessor follows; a held `data`
@@ -226,7 +227,7 @@ export type RecordMesh = Mesh & { _instances: MeshInstances & { matrix: null; no
  * Slot-bound to its mesh: created by addInstance, destroyed by
  * destroy; the generic add/remove reject it.
  */
-export type InstanceNode = SceneNode & {
+export type InstanceNode = SceneNode & HoverHandlers & {
   kind: "instance"
   /** The owning mesh; null once removed (the handle is inert). */
   mesh: InstancedMesh | null
@@ -287,9 +288,35 @@ export function createSprite(material: Material): Mesh {
   if (spriteQuad === undefined) spriteQuad = plane({ label: "sprite" })
   let mesh = createMesh(spriteQuad, material)
   mesh._sprite = true
+  uncullFlooredSprite(mesh)
   return mesh
 }
 
+/**
+ * The screen-size clamp a sprite mesh draws with, `[minPx, maxPx]` (0 =
+ * off): the mesh's own `uScreenPx` param over its material's (a sprite
+ * material always carries one). null when neither bound is on, or the
+ * material is not a sprite material.
+ */
+export function spriteScreenPx(mesh: Mesh): [number, number] | null {
+  let px = mesh._params?.uScreenPx ?? mesh.material.params.uScreenPx
+  if (px === undefined || typeof px === "number") return null
+  let min = px[0] ?? 0
+  let max = px[1] ?? 0
+  return min > 0 || max > 0 ? [min, max] : null
+}
+
+// A floored sprite draws larger than its unit box far from the camera,
+// so the frustum test would hide it while its quad is on screen: a floor
+// coming on (at creation, a material swap, a params override) switches
+// the mesh's culling off. Only ever off - an app that wants it back says
+// so with setCulling.
+function uncullFlooredSprite(mesh: Mesh): void {
+  if (!mesh._sprite || !mesh.frustumCulled) return
+  let px = spriteScreenPx(mesh)
+  if (px !== null && px[0] > 0) setCulling(mesh, { frustumCulled: false })
+}
+
 /** The local box picking and sorting work from: explicit instance bounds
  * when the mesh is instanced (null without them - no leaf, no hits), the
  * unit box for a sprite, the geometry's own bounds otherwise. */
@@ -866,6 +893,30 @@ export function instanceAttribute(mesh: InstancedMesh | RecordMesh, name: string
   return null
 }
 
+/**
+ * The mirror of record stream `stream` (default the first: a record
+ * mesh's records, an instanced mesh's style records) - the raw power
+ * path for a population written in bulk: `capacity` records at the
+ * layout's stride, a Float32Array over an all-float layout, bytes
+ * otherwise (write those through instanceAttribute's codecs, or a typed
+ * view of your own over the format). Write it, then updateRecords the
+ * range. Read it AT USE TIME: growth (setRecords past capacity,
+ * addInstance past it) replaces the mirror, and a hoisted view becomes a
+ * dead copy whose writes publish nothing. Throws on a transferred
+ * population (no mirror) and a disposed one. @solidrt/2d's
+ * records(layer).
+ */
+export function records(mesh: InstancedMesh | RecordMesh, stream = 0): ArrayBufferView {
+  let inst: MeshInstances | null = mesh._instances
+  if (inst === null) throw new Error("records: the mesh's instances are disposed")
+  if (inst.transfer) throw new Error("records: the records were transferred at creation (transfer: true) - there is no mirror to read or write")
+  let s = inst.streams[stream]
+  if (!Number.isInteger(stream) || s === undefined) {
+    throw new Error("records: stream " + stream + " is out of range; the mesh has record streams 0.." + (inst.streams.length - 1))
+  }
+  return s.data
+}
+
 /** Options of `updateRecords`: the stream (default 0) and the record
  * range (default the whole stream, capacity wide). */
 export type UpdateRecordsOptions = { stream?: number; first?: number; count?: number }
@@ -1336,6 +1387,7 @@ export function setDrawRange(mesh: Mesh, first: number, count?: number): void {
 export function setMaterial(mesh: Mesh, material: Material): void {
   if (mesh.material === material) return
   mesh.material = material
+  uncullFlooredSprite(mesh)
   rebuildEntry(mesh)
 }
 
@@ -1359,5 +1411,6 @@ function rebuildEntry(mesh: Mesh): void {
 export function setMeshParams(mesh: Mesh, params: ShaderParams): void {
   if (mesh._params === null) mesh._params = {}
   Object.assign(mesh._params, params)
+  if (params.uScreenPx !== undefined) uncullFlooredSprite(mesh)
   mesh._scene?._setParams(mesh, params)
 }

package/src/node.ts

@@ -180,6 +180,15 @@ export type SceneHooks = {
  * cross-fade band. Re-applied whenever the node enters a scene. */
 export type LodConfig = { levels: { node: SceneNode | null; size: number }[]; fade: number }
 
+/** The hover pair, on the nodes a ray can strike (Mesh, InstanceNode):
+ * enter/leave fire on the struck node alone and never bubble, so a group
+ * or a light carries none - the 2d package's Sprite against its
+ * SpriteGroup. */
+export type HoverHandlers = {
+  onPointerEnter?: (event: NodePointerEvent) => void
+  onPointerLeave?: (event: NodePointerEvent) => void
+}
+
 export type SceneNode = {
   kind: "group" | "mesh" | "light" | "instance"
   parent: SceneNode | null
@@ -198,14 +207,13 @@ export type SceneNode = {
    * nearest hit - the struck instance of an instanced mesh, else the mesh
    * - bubble through its ancestors and end at the scene's listeners
    * (stopPropagation stops the walk, and a stopped down claims the whole
-   * press); enter/leave fire on the struck node alone. Events flow once
-   * the element showing the scene carries `scene.handlers`. */
+   * press); enter/leave are the struck node's own (HoverHandlers, on Mesh
+   * and InstanceNode). Events flow once the element showing the scene
+   * carries `scene.handlers`. */
   onPointerDown?: (event: NodePointerEvent) => void
   onPointerMove?: (event: NodePointerEvent) => void
   onPointerUp?: (event: NodePointerEvent) => void
   onPointerCancel?: (event: NodePointerEvent) => void
-  onPointerEnter?: (event: NodePointerEvent) => void
-  onPointerLeave?: (event: NodePointerEvent) => void
   /** The wheel over the node (NodeWheelEvent: `deltaX`/`deltaY`), bubbling
    * like down/move/up. */
   onWheel?: (event: NodeWheelEvent) => void

package/src/orbit.ts

@@ -101,7 +101,9 @@
 // at once (the next paint carries the new camera, no frame loop needed
 // for a drag), and update(dt) integrates the rates, the auto-orbit, the
 // motion, the follow, the lanes and the occlusion return from the app's
-// own onFrame - the control registers no frame loop of its own. Only
+// own onFrame (onBeforeRender when it follows something the frame moves,
+// so it sees the frame's final pose) - the control registers no frame
+// loop of its own. Only
 // `orbiting` and `active` are reactive: slow UI state a HUD reads, and
 // the frame-loop gate. update() returns whether the camera changed since
 // the previous update (pushes included), so per-frame dependents
@@ -303,8 +305,10 @@ export type OrbitCamera = {
   active(): boolean
   /** Integrate the axis rates, the auto-orbit, the motion, the follow,
    * the lanes and the occlusion return over dt seconds and push any
-   * camera change. Call from onFrame; returns whether the camera changed
-   * since the previous update (nudges and verbs included). */
+   * camera change. Call from onFrame - or from onBeforeRender when the
+   * control follows something the frame moves, so it reads that frame's
+   * final pose; returns whether the camera changed since the previous
+   * update (nudges and verbs included). */
   update(dt: number): boolean
   /** The input abstraction: `rotate` (vec2, element heights of drag /
    * turns per second), `zoom` (axis, octaves, positive in), `pan` (vec2,
@@ -325,9 +329,12 @@ export type OrbitCamera = {
    * camera's right and up (or the ground plane, `panPlane`), through
    * `clampPose`, and push. */
   panBy(right: number, up: number): void
-  /** Re-seat the pivot at a world point without moving the picture: the
-   * point is projected onto the view axis and becomes the target at that
-   * depth. Points at or behind the eye are ignored. */
+  /** Re-seat the pivot (the orbit target, the point the camera turns
+   * about - the 2d camera's pose point, which that control places ON
+   * SCREEN by its `pivot` fraction and moves in world space by its pose)
+   * at a world point without moving the picture: the point is projected
+   * onto the view axis and becomes the target at that depth. Points at
+   * or behind the eye are ignored. */
   setPivot(point: Vec3): void
   /** Re-seat the pivot at a world point EXACTLY, without moving the
    * picture: the target becomes the point, the distance its depth, and

package/src/scene-pointer.ts

@@ -116,7 +116,7 @@ export function makePointerInput(deps: PointerInputDeps): PointerInput {
   let sameHit = (hit: Hit, target: Target): boolean => hit.mesh === target.mesh && (hit.instance ?? null) === target.instance
   let sameTarget = (a: Target | null, b: Target | null): boolean => (a === null ? b === null : b !== null && a.mesh === b.mesh && a.instance === b.instance)
   // The node the walk starts at, and the one enter/leave fire on.
-  let nodeOf = (target: Target): SceneNode => target.instance ?? target.mesh
+  let nodeOf = (target: Target): Mesh | InstanceNode => target.instance ?? target.mesh
   // The captured target's own hit, if the ray still strikes it.
   let hitOn = (target: Target | null, x: number, y: number): Hit | null => {
     if (target === null) return null

package/src/scene-shadows.ts

@@ -99,7 +99,7 @@ export type ShadowSystemDeps<V extends ShadowView> = {
   disposeView(view: V): void
   /** The light set changed shape: the scene owes a writeLights. */
   markLightsDirty(): void
-  /** Schedule the scene's sync microtask. */
+  /** Schedule the scene's sync. */
   schedule(): void
 }
 

package/src/scene.ts

@@ -13,15 +13,17 @@
 // coverage (stored and skipped until a declaring material arrives), so no
 // bookkeeping tracks who reads them. scene.setParams merges app-owned
 // names into the same set.
-// Mutations batch to a microtask, so a burst of writes (a whole subtree
-// moved, many effects in one flush) syncs once.
+// Mutations batch, so a burst of writes (a whole subtree moved, many
+// effects in one flush) syncs once: in the publish pass of core's
+// onBeforeRender, ahead of the frame's paint, or at a microtask for a
+// write made outside a frame.
 //
 // Rendering itself belongs to the runtime: the target is an ordinary
 // `render: "auto"` draw target that re-renders when its entries change, so
 // a static scene costs zero passes and this module registers no frame
 // loop. Continuous animation is the app's onFrame writing transforms -
-// each write lands in the core, the microtask flushes it, and the frame
-// renders once.
+// each write lands in the core, the sync ahead of the paint flushes it,
+// and the frame renders once.
 //
 // Still in JS this stage (see okf/backlog/spatial-core.md): the picking
 // broadphase and its leaves, the transparent sort's centers and the light
@@ -36,11 +38,11 @@
 // and pointer subsystems are scene-shadows.ts / scene-pointer.ts,
 // built here with the scene's seams as their deps.
 
-import { addDraw, createCubeDrawTarget, createDrawTarget, depthTexture, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, renderTarget, setDrawBuffers, setDrawParams, setDrawRange, setDrawTextures, setTargetParams, setTargetRect, setTargetSize, setTargetTextures } from "@solidrt/core/gpu"
+import { addDraw, createCubeDrawTarget, createDrawTarget, depthTexture, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, renderTarget, screenSizeScale, setDrawBuffers, setDrawParams, setDrawRange, setDrawTextures, setTargetParams, setTargetRect, setTargetSize, setTargetTextures } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
 import type { BindDrawOptions, Impact as CoreImpact, NodeId, QueryFilter } from "flux:spatial"
 import type { BufferId, DrawId, FilterMode, InstanceOrder, ProgramId, RenderPipelineId, ShaderParams, TextureBindings, TextureId, WrapMode } from "@solidrt/core/gpu"
-import { getOwner, onCleanup } from "@solidrt/core"
+import { getOwner, onBeforeRender, onCleanup, runWithOwner } from "@solidrt/core"
 import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
 import { copy, mat4, transformPoint } from "./math.ts"
 import { linearColor, premultipliedColor } from "./color.ts"
@@ -61,9 +63,9 @@ import type { EnvironmentOptions, Prefilter } from "./environment.ts"
 
 export type { EnvironmentOptions } from "./environment.ts"
 import type { Material } from "./material.ts"
-import { activateMorph, fillTransform, freeLeaving, leaveScene, makeNode, setTransition } from "./node.ts"
+import { activateMorph, fillTransform, freeLeaving, leaveScene, makeNode, setTransition, worldInto } from "./node.ts"
 import type { SceneHooks, SceneNode, ScenePointerListener } from "./node.ts"
-import { checkInstancePairing, checkMask, checkOrderPairing, drawCount, instanceBinding, localBounds, markLiveRecords, publishRecords } from "./mesh.ts"
+import { checkInstancePairing, checkMask, checkOrderPairing, drawCount, instanceBinding, localBounds, markLiveRecords, publishRecords, spriteScreenPx } from "./mesh.ts"
 import type { InstancedMesh, InstanceNode, Mesh, MeshInstances, ResolvedInstanceOrder } from "./mesh.ts"
 import type { CastingLight, Light } from "./light.ts"
 
@@ -470,7 +472,7 @@ export type SceneOptions = {
    * { stagger })` at creation: every node added straight under the root
    * that enters or leaves in one frame is spaced by `index * stagger`,
    * the whole-scene form of a Group's stagger (nested groups declaring
-   * their own win for what is under them). */
+   * their own win for what is under them). See setStagger. */
   stagger?: number
   /** `autoFree: false` opts out of owner-scoped auto-dispose (then call dispose yourself). */
   autoFree?: boolean
@@ -482,7 +484,8 @@ export type SceneOptions = {
   /** Where a per-scene budget error goes: the light cap and the
    * shadow-slot budget are checked over the settled set at the sync and
    * reported once per change of the set, the scene rendering on with
-   * what fits. Without a handler the sync throws it, uncaught (a
+   * what fits. Without a handler the sync throws it, and it is only
+   * reported (logged by the frame's publish pass, or uncaught from the
    * microtask): the `<Scene>` component hands one in and rethrows inside
    * the tree, so the app's error boundary shows it. */
   onError?: (error: Error) => void
@@ -827,6 +830,9 @@ export type Scene = {
    * measured projected size, for the scene, its views and its shadow
    * tiles. Below 1 switches to far levels sooner. */
   setLodBias(bias: number): void
+  /** Stagger (ms) on the scene's root node, live (SceneOptions.stagger
+   * is its creation form): null removes it. The 2d layer's setStagger. */
+  setStagger(ms: number | null): void
   /** The level a LOD group draws in the scene's own render (the thing to
    * read while tuning thresholds): the index into its levels, nearest
    * first, `levels.length` when culled past the last one, null before
@@ -1583,8 +1589,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let inst = mesh._instances
     let bufs = mesh._buffers!
     // The entry starts switched off: it has no world matrix yet - the walk
-    // in sync() computes one - and _schedule() defers that to a microtask,
-    // so added live it would draw at the seeded identity until then. The
+    // in sync() computes one - and _schedule() defers that to the sync
+    // (the frame's publish pass, or a microtask), so added live it would
+    // draw at the seeded identity until then. The
     // mismatch branch in sync() turns it on in the same pass that writes
     // uModel.
     let morph = morphEntry(mesh.material, mesh)
@@ -2270,6 +2277,21 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   // first frame.
   lightsDirty = true
   hooks._schedule()
+  // The publish pass of every frame runs the pending sync ahead of the
+  // paint, so a write made anywhere in the frame's JS is in that frame's
+  // picture: the count, the buffers and the bytes of a record write land
+  // together, and nothing shows a frame late. The microtask stays for
+  // writes made outside a frame. Registered outside any owner: the scene's
+  // own dispose unhooks it (an autoFree: false scene outlives the owner it
+  // was created in).
+  let unhook = runWithOwner(null, () =>
+    onBeforeRender(
+      () => {
+        if (scheduled) sync()
+      },
+      { publish: true },
+    ),
+  )
 
   // The scene's root listeners (scene.listen): the last stop of the
   // pointer walk scene-pointer.ts runs behind scene.handlers.
@@ -2303,6 +2325,101 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     return hits
   }
 
+  // Sprites under a screen-size clamp (the sprite material's
+  // minScreenPx/maxScreenPx) draw at a size the index does not know: the
+  // vertex stage scales the quad by the pixels one unit covers at its
+  // depth under THE CAMERA DRAWING IT. So a pick - which has a camera -
+  // replaces the ray's hits on them with an exact ray-quad test at the
+  // drawn size: the quad's basis as the stage builds it (camera right and
+  // up, or a fixed-y sprite's yaw basis), the scale from core's
+  // screenSizeScale over the stage's own pixels-per-unit derivation. The
+  // world-space raycast keeps the index's answer. Reads pickOrigin/pickDir
+  // as pixelRayOf left them; `th` is the target's pixel height the stage
+  // sees as uViewport.y.
+  let spriteWorld = mat4()
+  let spriteClip: Vec4 = [0, 0, 0, 0]
+  let spriteProbe: Vec3 = [0, 0, 0]
+  let shown = (node: SceneNode | null): boolean => {
+    for (; node !== null; node = node.parent) if (!node.visible) return false
+    return true
+  }
+  let clampedSpriteHit = (mesh: Mesh, px: [number, number], cam: Camera, th: number): Hit | null => {
+    let m = worldInto(spriteWorld, mesh)
+    let cx = m[12], cy = m[13], cz = m[14]
+    let w = Math.hypot(m[0], m[1], m[2])
+    let h = Math.hypot(m[4], m[5], m[6])
+    let v = cam.view
+    let upX = v[1], upY = v[5], upZ = v[9]
+    spriteProbe[0] = cx
+    spriteProbe[1] = cy
+    spriteProbe[2] = cz
+    transformPoint(spriteClip, cam.viewProj, spriteProbe)
+    let cw = spriteClip[3]
+    if (!(cw > 1e-6)) return null
+    let centerNdcY = spriteClip[1] / cw
+    spriteProbe[0] = cx + upX
+    spriteProbe[1] = cy + upY
+    spriteProbe[2] = cz + upZ
+    transformPoint(spriteClip, cam.viewProj, spriteProbe)
+    let pxPerUnit = Math.abs(spriteClip[1] / spriteClip[3] - centerNdcY) * 0.5 * th
+    let s = screenSizeScale(w, h, pxPerUnit, px[0], px[1])
+    let halfW = (w * s) / 2
+    let halfH = (h * s) / 2
+    let rx: number, ry: number, rz: number
+    if (mesh.material.billboard === "fixed-y") {
+      let tx = cam.eye[0] - cx
+      let tz = cam.eye[2] - cz
+      let len = Math.hypot(tx, tz)
+      if (len > 1e-6) {
+        rx = tz / len
+        ry = 0
+        rz = -tx / len
+      } else {
+        rx = 1
+        ry = 0
+        rz = 0
+      }
+      upX = 0
+      upY = 1
+      upZ = 0
+    } else {
+      rx = v[0]
+      ry = v[4]
+      rz = v[8]
+    }
+    // The quad's normal, right x up; the ray meets the plane at t.
+    let nx = ry * upZ - rz * upY
+    let ny = rz * upX - rx * upZ
+    let nz = rx * upY - ry * upX
+    let ox = pickOrigin[0], oy = pickOrigin[1], oz = pickOrigin[2]
+    let dx = pickDir[0], dy = pickDir[1], dz = pickDir[2]
+    let denom = dx * nx + dy * ny + dz * nz
+    if (Math.abs(denom) < 1e-12) return null
+    let t = ((cx - ox) * nx + (cy - oy) * ny + (cz - oz) * nz) / denom
+    if (t <= 0) return null
+    let hx = ox + t * dx, hy = oy + t * dy, hz = oz + t * dz
+    let lx = (hx - cx) * rx + (hy - cy) * ry + (hz - cz) * rz
+    let ly = (hx - cx) * upX + (hy - cy) * upY + (hz - cz) * upZ
+    if (Math.abs(lx) > halfW || Math.abs(ly) > halfH) return null
+    // Facing the ray, like every core hit; distance along the normalized ray.
+    let flip = denom > 0 ? -1 : 1
+    return { mesh, distance: t * Math.hypot(dx, dy, dz), point: [hx, hy, hz], normal: [nx * flip, ny * flip, nz * flip] }
+  }
+  let clampSpriteHits = (hits: Hit[], cam: Camera, th: number): Hit[] => {
+    let out: Hit[] | null = null
+    for (let mesh of meshes) {
+      if (!mesh._sprite) continue
+      let px = spriteScreenPx(mesh)
+      if (px === null) continue
+      if (out === null) out = hits.filter(hit => !(hit.mesh._sprite && spriteScreenPx(hit.mesh) !== null))
+      if ((mesh.layers & sceneMask) === 0 || !shown(mesh)) continue
+      let hit = clampedSpriteHit(mesh, px, cam, th)
+      if (hit !== null) out.push(hit)
+    }
+    if (out === null) return hits
+    return out.sort((a, b) => a.distance - b.distance)
+  }
+
   let scene: Scene = {
     texture: resolve === null ? texture : resolve.target,
     hdrTexture: texture,
@@ -2323,6 +2440,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       hooks._schedule()
     },
     size: () => ({ width, height }),
+    setStagger(ms) {
+      if (disposed) return
+      setTransition(root, ms === null ? null : { stagger: ms })
+    },
     setParams(params) {
       if (disposed) return
       Object.assign(sceneParams, params)
@@ -2443,7 +2564,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     },
     pick(x, y) {
       pixelRay(x, y)
-      return raycastAs(texture, pickOrigin, pickDir, undefined)
+      return clampSpriteHits(raycastAs(texture, pickOrigin, pickDir, undefined), camera, height)
     },
     unproject(x, y, w, out = [0, 0, 0]) {
       pixelRay(x, y)
@@ -2590,7 +2711,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         pick(x, y) {
           if (v.disposed) return []
           pixelRayOf(v.camera, v.width, v.height, x, y)
-          return raycastAs(v.texture, pickOrigin, pickDir, undefined)
+          return clampSpriteHits(raycastAs(v.texture, pickOrigin, pickDir, undefined), v.camera, v.height)
         },
         project(point) {
           return projectWith(v.camera, v.width, v.height, point)
@@ -2656,6 +2777,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     dispose() {
       if (disposed) return
       disposed = true
+      unhook()
       listeners.clear()
       // Full tree-side teardown, not just the target: every node leaves
       // the scene (entries' geometry-buffer references and pick leaves