@solidrt/2d 0.0.66 → 0.0.68

package/src/layer.ts

@@ -13,10 +13,18 @@
 // Two instance-buffer slots split ownership: slot 0 is the pose buffer,
 // written ONLY by the core (one coalesced write per flush however many
 // nodes moved); slot 1 is the style buffer [u0, v0, u1, v1, tint rgba,
-// renderOrder], JS-owned and published through the zero-copy write lease. Never write
-// the pose buffer from JS - the core's staging mirror is the owner and
-// will overwrite. For motion only JS can compute at large populations, the
-// records layer (records.ts) is the escape hatch.
+// renderOrder, minScreenPx, maxScreenPx, atlas], JS-owned and published
+// through the zero-copy write lease. Never write the pose buffer from JS -
+// the core's staging mirror is the owner and will overwrite. For motion
+// only JS can compute at large populations, the records layer (records.ts)
+// is the escape hatch.
+//
+// A layer draws from the ATLASES it declares at creation, bound together
+// as one draw: every frame carries its texture, the style record stores
+// that texture's index in the list, and the generated fragment stage
+// (shaders.ts) picks the sampler per instance - so sprites from several
+// sheets interleave freely in one draw, key order included, and a frame
+// from a sheet the layer did not declare throws at the write.
 //
 // Sprites hold FIXED instance slots (freed slots recycle): draw order is
 // slot order, so removal never shifts records and pose sinks never rebind.
@@ -25,10 +33,10 @@
 // CameraUpdate in camera.ts) is a shared-params write (uCamera +
 // uCameraRot) on that view's target, never per-sprite; pointer dispatch
 // (dispatch.ts) undoes it with unprojectCamera.
-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 { beginBufferWrite, createBuffer, destroyBuffer, endBufferWrite } from "@solidrt/core/gpu"
-import type { BufferId, TextureId } from "@solidrt/core/gpu"
+import { beginBufferWrite, checkScreenSize, createBuffer, destroyBuffer, endBufferWrite, screenSizeScale } from "@solidrt/core/gpu"
+import type { BlendMode, BufferId, TextureId } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
 import type {
   Impact as CoreImpact,
@@ -41,10 +49,13 @@ import type {
   QueryFilter,
 } from "flux:spatial"
 import { on } from "sol:events"
+import { checkAtlases, frameIndex } from "./atlas.ts"
+import type { Atlas } from "./atlas.ts"
 import type { CameraState, CameraUpdate } from "./camera.ts"
 import type { Frame } from "./frames.ts"
-import { FULL_FRAME, writeFrame } from "./frames.ts"
+import { fullFrame, isFrame, writeFrame } from "./frames.ts"
 import type { RecordLayer } from "./records.ts"
+import { floorReach, pointInSprite } from "./pick.ts"
 import { createSpritePipeline, INSTANCE_LAYOUTS_SPLIT, VERTEX_SPLIT } from "./shaders.ts"
 import { createViews } from "./views.ts"
 import type { ViewHandle, ViewOptions } from "./views.ts"
@@ -55,12 +66,23 @@ export const POSE_FLOATS = 5
 // Float offset of world y in a pose record - what `orderBy: "y"` keys on.
 const POSE_Y_FIELD = 1
 /** Floats per style record:
- * [u0, v0, u1, v1, tintR, tintG, tintB, tintA, renderOrder]. */
-export const STYLE_FLOATS = 9
+ * [u0, v0, u1, v1, tintR, tintG, tintB, tintA, renderOrder, minScreenPx,
+ * maxScreenPx, atlas, outlineR, outlineG, outlineB, outlineWidth]. */
+export const STYLE_FLOATS = 16
 
 // Float offset of renderOrder in a style record - what `orderBy: "renderOrder"`
 // keys on.
 const STYLE_KEY_FIELD = 8
+// Float offsets of the screen-size clamp in a style record.
+const STYLE_MIN_PX_FIELD = 9
+const STYLE_MAX_PX_FIELD = 10
+// Float offset of the outline (rgb plus width in world pixels) a
+// distance-field atlas draws under the sprite; text runs write it, a
+// colour atlas ignores it.
+const STYLE_OUTLINE_FIELD = 12
+// Float offset of the atlas sampler index (the frame's texture's position
+// in the layer's atlas list).
+const STYLE_ATLAS_FIELD = 11
 
 const RESOLVED = Promise.resolve()
 
@@ -183,6 +205,9 @@ export type Sprite = {
   onPointerDown?: (event: SpritePointerEvent) => void
   onPointerMove?: (event: SpritePointerEvent) => void
   onPointerUp?: (event: SpritePointerEvent) => void
+  /** The pointer's other end: the system took it away (see core's
+   * onPointerCancel); bubbles like up, and the press it ends never taps. */
+  onPointerCancel?: (event: SpritePointerEvent) => void
   onPointerEnter?: (event: SpritePointerEvent) => void
   onPointerLeave?: (event: SpritePointerEvent) => void
   /** A wheel notch over the sprite; bubbles like down/move/up. */
@@ -216,7 +241,9 @@ export type SpriteOptions = {
   /** Drawn size in layer pixels. */
   w?: number
   h?: number
-  /** Atlas frame (normalized UVs); default the whole atlas. */
+  /** Atlas frame (a texture plus normalized UVs, from grid/namedFrames/
+   * fullFrame); default the whole first atlas of the layer. Its texture
+   * must be one of the layer's `atlases`, else the write throws. */
   frame?: Frame
   /** Mirror the frame horizontally / vertically about the sprite's center.
    * A UV-side mirror: w/h stay the drawn size, a scale transition never
@@ -227,12 +254,33 @@ export type SpriteOptions = {
   rotation?: number
   /** RGBA multiplier 0..1 each; default opaque white (the texture as-is). */
   tint?: [number, number, number, number]
+  /**
+   * The screen-size clamp's floor, view pixels (default 0: off). Whatever
+   * the camera's zoom, the sprite draws at least this big on its smaller
+   * axis, scaled uniformly so its aspect holds - a selection ring that
+   * stays findable at the overview, a map pin, a traffic dot that never
+   * falls under two device pixels. A floored sprite is world-sized until
+   * zoom shrinks it to the floor, then holds there. Applied in the vertex
+   * stage over the pose the core writes (core's screenSizeScale), so it
+   * comes after group scale and a size transition, and rotation stays
+   * world-space; `pick` honours it at the zoom it is asked for. A
+   * collapsed sprite (zero w or h) stays collapsed. Finite, >= 0.
+   */
+  minScreenPx?: number
+  /**
+   * The clamp's ceiling, view pixels (default 0: off): the sprite draws
+   * at most this big on its smaller axis however far the camera zooms in
+   * - a label marker that must not balloon. Equal to `minScreenPx` it is
+   * a constant screen size, Three's `sizeAttenuation: false`, and `w`/`h`
+   * then carry the aspect alone. Never below a floor that is on.
+   */
+  maxScreenPx?: number
   /**
    * Explicit draw-order key, read only by a layer created with `orderBy:
    * "renderOrder"` (default 0; ties keep slot order, so untouched sprites draw
    * as without one). The raise idiom: `setSprite(hit, { renderOrder: ++top })`
    * on interaction, back to 0 to restore. Node layer only - a record
-   * layer's 13-float record has no key field (order it by one of its own
+   * layer's 16-float record has no key field (order it by one of its own
    * fields with `orderBy: { field }`); setting this there throws.
    */
   renderOrder?: number
@@ -343,6 +391,7 @@ export type LayerPointerListener = {
   onPointerDown?: (event: LayerPointerEvent) => void
   onPointerMove?: (event: LayerPointerEvent) => void
   onPointerUp?: (event: LayerPointerEvent) => void
+  onPointerCancel?: (event: LayerPointerEvent) => void
   onWheel?: (event: LayerWheelEvent) => void
   onTap?: (event: LayerTapEvent) => void
 }
@@ -353,6 +402,7 @@ export type LayerHandlers = {
   onPointerDown: (event: ElementPointerEvent) => void
   onPointerMove: (event: ElementPointerEvent) => void
   onPointerUp: (event: ElementPointerEvent) => void
+  onPointerCancel: (event: ElementPointerEvent) => void
   onPointerLeave: (event: ElementPointerEvent) => void
   onWheel: (event: ElementWheelEvent) => void
 }
@@ -376,6 +426,14 @@ export type SpriteLayerOptions = {
    * tint in every view; default opaque white (sprites as-is). See
    * setTint. */
   tint?: [number, number, number, number]
+  /**
+   * How the sprites blend into the layer's targets, core gpu's BlendMode;
+   * default "alpha" (premultiplied source-over in draw order). "add" for
+   * glows, explosions and additive particles, "multiply" to darken, "none"
+   * to overwrite. Pipeline state, fixed at creation: an additive layer is
+   * a second layer over the same atlas.
+   */
+  blend?: BlendMode
   /** Names the GPU resources (buffers, pipeline; views default to
    * `<label>-view`); default "sprites". */
   label?: string
@@ -447,6 +505,7 @@ export type SpriteGroup = {
   onPointerDown?: (event: SpritePointerEvent) => void
   onPointerMove?: (event: SpritePointerEvent) => void
   onPointerUp?: (event: SpritePointerEvent) => void
+  onPointerCancel?: (event: SpritePointerEvent) => void
   onWheel?: (event: SpriteWheelEvent) => void
   onTap?: (event: SpriteTapEvent) => void
   /** See Sprite.onTransitionEnd. */
@@ -483,6 +542,15 @@ export type GroupOptions = {
  * and a Godot World2D only through Viewports.
  */
 export type LayerBase = {
+  /**
+   * The atlases the layer draws from, as declared at creation: every
+   * frame written to the layer names one of their textures, and a
+   * record's `atlas` field is the texture's index in this list (what a
+   * raw record writer stores). Bound together as one draw per view -
+   * the multi-texture batch, so sprites from different sheets interleave
+   * in draw order.
+   */
+  readonly atlases: readonly Atlas[]
   /** Live sprite count. */
   readonly count: number
   /**
@@ -500,8 +568,11 @@ export type LayerBase = {
    * Topmost means draw order (highest slot on the node layer, last added
    * on a record layer); an `orderBy` key is not consulted (see
    * SpriteLayerOptions.orderBy's known limitation). World space: a view
-   * undoes its camera before asking. */
-  pick(x: number, y: number): Sprite[]
+   * undoes its camera before asking, and passes its camera's `zoom` so a
+   * sprite's screen-size floor (SpriteOptions.minScreenPx) is hit at the
+   * size it draws; default 1 (the unzoomed world). The pointer walk and
+   * `view.pick` do both. */
+  pick(x: number, y: number, zoom?: number): Sprite[]
   /**
    * A rendering of the layer's world from a camera of its own - the main
    * view, a minimap, a zoomed inset, one split-screen pane -
@@ -595,7 +666,8 @@ export type SpriteLayer = LayerBase & {
    * Every shown sprite whose rotated rect overlaps the layer-pixel rect
    * (the core BVH overlap query, exact for rotated sprites), unordered -
    * the marquee query: `overlap` over an unrotated rect, sprites only.
-   * Node layer only.
+   * Node layer only. A world-space query like overlap and sweep: the
+   * sprites' world rects, never a screen-size floor (that is `pick`'s).
    */
   pickRect(x: number, y: number, width: number, height: number): Sprite[]
   /**
@@ -651,15 +723,20 @@ export type SpriteLayer = LayerBase & {
    * scopes the layer's queries in the arena shared with 3d scenes. */
   _root: NodeId
   _destroyGroup(group: GroupState): void
+  /** Write a sprite's outline (rgb 0..1 and a width in world pixels)
+   * for a distance-field atlas to draw under it; internal, the text
+   * runs' write (text.ts). A colour atlas ignores the field. */
+  _outline(sprite: Sprite, r: number, g: number, b: number, width: number): void
 }
 
-/** The stored UVs at `at` un-mirrored by the sprite's flags: the frame as
- * the caller gave it. Internal - records.ts reads through it too. */
-export function readFrame(data: Float32Array, at: number, sprite: Sprite): Frame {
+/** The stored UVs at `at` un-mirrored by the sprite's flags, over the
+ * texture the record's atlas index resolved to: the frame as the caller
+ * gave it. Internal - records.ts reads through it too. */
+export function readFrame(data: Float32Array, at: number, sprite: Sprite, texture: TextureId): Frame {
   let u0 = data[at]!, v0 = data[at + 1]!, u1 = data[at + 2]!, v1 = data[at + 3]!
   return sprite._flipX || sprite._flipY
-    ? { u0: sprite._flipX ? u1 : u0, v0: sprite._flipY ? v1 : v0, u1: sprite._flipX ? u0 : u1, v1: sprite._flipY ? v0 : v1 }
-    : { u0, v0, u1, v1 }
+    ? { texture, u0: sprite._flipX ? u1 : u0, v0: sprite._flipY ? v1 : v0, u1: sprite._flipX ? u0 : u1, v1: sprite._flipY ? v0 : v1 }
+    : { texture, u0, v0, u1, v1 }
 }
 
 /** Fill the shared transform scratch: xy translation, z rotation, xy scale
@@ -729,14 +806,19 @@ function writeTransform(sprite: Sprite): void {
 }
 
 /**
- * Create a sprite layer over one atlas texture. It renders nothing by
- * itself: `layer.createView({ width, height })` (or a `<SpriteLayer>` /
- * `<View2d>`) is where it shows, once or many times. Disposed
- * automatically with the owning reactive scope (opt out with
- * `{ autoFree: false }`); the atlas is NOT owned - dispose it yourself
- * (it commonly outlives layers).
+ * Create a sprite layer over its atlases: the list of sheets (createAtlas
+ * records, or `{ texture, width, height }` literals) every frame written
+ * to it must come from, bound together as ONE draw - up to
+ * `limits.maxTextureUnits` of them (16 on every GLES 3.0 device), of any
+ * sizes and sampler states, interleaving freely in draw order. It
+ * renders nothing by itself: `layer.createView({ width, height })` (or a
+ * `<SpriteLayer>` / `<View2d>`) is where it shows, once or many times.
+ * Disposed automatically with the owning reactive scope (opt out with
+ * `{ autoFree: false }`); the atlases are NOT owned - dispose them
+ * yourself (they commonly outlive layers).
  */
-export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions): SpriteLayer {
+export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions): SpriteLayer {
+  let atlasIndex = checkAtlases("createSpriteLayer", atlases)
   let capacity = opts?.capacity ?? 1024
   if (!(capacity > 0 && Number.isInteger(capacity))) {
     throw new Error(`createSpriteLayer: capacity must be a positive integer, got ${capacity}`)
@@ -746,12 +828,46 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
   checkTint("createSpriteLayer", tint)
   let pose: BufferId = createBuffer(capacity * POSE_FLOATS * 4, { label: `${label}-pose`, autoFree: false })
   let style: BufferId = createBuffer(capacity * STYLE_FLOATS * 4, { label: `${label}-style`, autoFree: false })
-  let gpu = createSpritePipeline(label, VERTEX_SPLIT, INSTANCE_LAYOUTS_SPLIT)
+  let gpu = createSpritePipeline(label, VERTEX_SPLIT, INSTANCE_LAYOUTS_SPLIT, opts?.blend ?? "alpha", atlases)
+  // The sprites with a screen-size clamp (either bound on), and the
+  // furthest any of them reaches from its center at its floor (floorReach,
+  // view pixels): the candidate box a pick searches around the pointer. A
+  // write that could only widen the reach raises it in place; one that may
+  // have shrunk it (a clamped sprite leaving, its floor or aspect dropping)
+  // marks it dirty and the next pick recomputes over the set - exact, and
+  // no cost while the clamps are untouched. Empty set: the raycast fast
+  // path, and no exact test at all.
+  let clamped = new Set<SpriteState>()
+  let reach = 0
+  let reachDirty = false
+  let dropClamp = (sprite: SpriteState): void => {
+    if (clamped.delete(sprite)) reachDirty = true
+  }
+  // The pair check against the STORED bounds, before any write lands: a
+  // ceiling set alone must not drop below the floor already there.
+  let checkClamp = (verb: string, sprite: SpriteState, opts: SpriteOptions): void => {
+    if (opts.minScreenPx === undefined && opts.maxScreenPx === undefined) return
+    let at = sprite._slot * STYLE_FLOATS
+    checkScreenSize(verb, opts.minScreenPx ?? styleData[at + STYLE_MIN_PX_FIELD]!, opts.maxScreenPx ?? styleData[at + STYLE_MAX_PX_FIELD]!)
+  }
 
   let disposed = false
   let scheduled = false
   let styleDirty = false
   let published = 0
+  // The publish pass of every frame runs the pending flush ahead of the
+  // paint, so a write made anywhere in the frame's JS is in that frame's
+  // picture; the microtask stays for writes made outside a frame.
+  // Registered outside any owner: dispose unhooks it (an autoFree: false
+  // layer outlives the owner it was created in).
+  let unhook = runWithOwner(null, () =>
+    onBeforeRender(
+      () => {
+        if (scheduled) flush()
+      },
+      { publish: true },
+    ),
+  )
 
   // Slot allocation: freed slots recycle, the high-water mark is the
   // published instance count (a freed slot's pose zeroes - zero scale
@@ -829,7 +945,16 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
     styleDirty = true
   }
 
-  let writeStyle = (sprite: SpriteState, opts: SpriteOptions) => {
+  // A frame's atlas index, or a throw: run before ANY field of a write
+  // lands (pose included), so a frame from an undeclared sheet leaves the
+  // sprite as it was.
+  let frameAtlas = (verb: string, opts: SpriteOptions): number => {
+    if (opts.frame === undefined) return -1
+    if (!isFrame(opts.frame)) throw new Error(`${verb}: not a frame, got ${JSON.stringify(opts.frame)}`)
+    return frameIndex(verb, atlasIndex, opts.frame)
+  }
+
+  let writeStyle = (sprite: SpriteState, opts: SpriteOptions, atlas: number) => {
     let at = sprite._slot * STYLE_FLOATS
     let flipX = opts.flipX !== undefined && opts.flipX !== sprite._flipX
     let flipY = opts.flipY !== undefined && opts.flipY !== sprite._flipY
@@ -838,6 +963,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
     if (opts.frame !== undefined) {
       let f = opts.frame
       writeFrame(styleData, at, f.u0, f.v0, f.u1, f.v1, sprite._flipX, sprite._flipY)
+      styleData[at + STYLE_ATLAS_FIELD] = atlas
       styleDirty = true
     } else if (flipX || flipY) {
       // No new frame: toggle the changed axes on the stored UVs.
@@ -855,17 +981,34 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
       styleData[at + STYLE_KEY_FIELD] = opts.renderOrder
       styleDirty = true
     }
+    if (opts.minScreenPx !== undefined) {
+      styleData[at + STYLE_MIN_PX_FIELD] = opts.minScreenPx
+      styleDirty = true
+    }
+    if (opts.maxScreenPx !== undefined) {
+      styleData[at + STYLE_MAX_PX_FIELD] = opts.maxScreenPx
+      styleDirty = true
+    }
+    let min = styleData[at + STYLE_MIN_PX_FIELD]!
+    if (min > 0 || styleData[at + STYLE_MAX_PX_FIELD]! > 0) {
+      clamped.add(sprite)
+      let r = floorReach(sprite._w, sprite._h, min)
+      if (r >= reach) reach = r
+      else reachDirty = true
+    } else {
+      dropClamp(sprite)
+    }
   }
 
   let views = createViews({
     label,
     pipeline: gpu.pipeline,
     quad: gpu.quad,
-    atlas,
+    atlases: atlases.map(a => a.texture),
     buffers: () => [pose, style],
     count: () => published,
     tint: () => tint,
-    pick: (x, y) => layer.pick(x, y),
+    pick: (x, y, zoom) => layer.pick(x, y, zoom),
     // The order key one view entry declares: "y" on world y in the pose
     // record (slot 0), "renderOrder" on the app-owned key in the style
     // record (slot 1); either way the core gathers BOTH buffers under the
@@ -880,6 +1023,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
   })
 
   let layer: SpriteLayer = {
+    atlases,
     get count() {
       return byNode.size
     },
@@ -893,21 +1037,57 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
       if (disposed) throw new Error("createView: layer is disposed")
       return views.create(vopts)
     },
-    pick(x, y) {
+    pick(x, y, zoom = 1) {
       // The index reads as of the last core flush; run any pending batch
       // first so a write followed by a pick sees the write.
       if (scheduled) flush()
+      filter.nodes = undefined
+      if (!(zoom > 0)) throw new Error(`pick: zoom must be positive, got ${zoom}`)
+      let out: Sprite[] = []
       RAY_ORIGIN[0] = x
       RAY_ORIGIN[1] = y
       RAY_ORIGIN[2] = PICK_RAY_START
       RAY_DIR[0] = 0
       RAY_DIR[1] = 0
       RAY_DIR[2] = 1
-      filter.nodes = undefined
-      let out: Sprite[] = []
-      for (let hit of spatial.raycast(RAY_ORIGIN, RAY_DIR, filter)) {
-        let sprite = byNode.get(hit.node)
-        if (sprite) out.push(sprite)
+      if (clamped.size === 0) {
+        for (let hit of spatial.raycast(RAY_ORIGIN, RAY_DIR, filter)) {
+          let sprite = byNode.get(hit.node)
+          if (sprite) out.push(sprite)
+        }
+      } else {
+        // A clamped sprite draws at another size than its index column:
+        // larger under a floor, smaller under a ceiling. The candidates
+        // are every column containing the point (the ray) plus, when a
+        // floor is on, every column within the widest floor's reach of it
+        // (a box overlap - a SURFACE contact in the core, so a box lying
+        // inside a big column reports nothing, which is why the ray stays
+        // in the union), each then tested exactly against its drawn rect:
+        // the world pose from the node's world matrix (the in-flight pose,
+        // group scale composed), scaled by its clamp at this zoom - what
+        // the vertex stage draws.
+        if (reachDirty) {
+          reach = 0
+          for (let s of clamped) reach = Math.max(reach, floorReach(s._w, s._h, styleData[s._slot * STYLE_FLOATS + STYLE_MIN_PX_FIELD]!))
+          reachDirty = false
+        }
+        let candidates = new Set<NodeId>()
+        for (let hit of spatial.raycast(RAY_ORIGIN, RAY_DIR, filter)) candidates.add(hit.node)
+        if (reach > 0) {
+          let half = reach / zoom
+          packVolume({ x: x - half, y: y - half, width: 2 * half, height: 2 * half }, "pick")
+          for (let hit of spatial.overlap("box", BOX, filter)) candidates.add(hit.node)
+        }
+        for (let node of candidates) {
+          let sprite = byNode.get(node)
+          if (!sprite) continue
+          spatial.worldMatrix(sprite.node!, WORLD)
+          let w = Math.hypot(WORLD[0]!, WORLD[1]!)
+          let h = Math.hypot(WORLD[4]!, WORLD[5]!)
+          let at = sprite._slot * STYLE_FLOATS
+          let scale = screenSizeScale(w, h, zoom, styleData[at + STYLE_MIN_PX_FIELD]!, styleData[at + STYLE_MAX_PX_FIELD]!)
+          if (pointInSprite(x, y, WORLD[12]!, WORLD[13]!, w * scale, h * scale, Math.atan2(WORLD[1]!, WORLD[0]!))) out.push(sprite)
+        }
       }
       // Topmost first: higher slot = drawn later = on top.
       return out.sort((a, b) => b._slot - a._slot)
@@ -989,6 +1169,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
     dispose() {
       if (disposed) return
       disposed = true
+      unhook()
       for (let sprite of byNode.values()) {
         sprite.layer = null
         declared.delete(sprite.node!)
@@ -1001,6 +1182,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
         spatial.destroyNode(group.node)
       }
       layer._groups.clear()
+      clamped.clear()
       // Corpses mid-exit go now: their slots must not outlive the buffer.
       for (let node of leaving) {
         freeing.delete(node)
@@ -1018,6 +1200,22 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
     },
     _add(opts) {
       if (disposed) throw new Error("addSprite: layer is disposed")
+      // The style bag with its defaults - renderOrder and the clamp at 0
+      // explicitly, since a recycled slot holds the previous occupant's
+      // values otherwise - resolved before a slot or node is taken, so a
+      // bad frame allocates nothing. An absent key and an explicit
+      // undefined both take the default (the options convention
+      // everywhere; a plain spread would let undefined win).
+      let style: SpriteOptions = {
+        ...opts,
+        frame: opts?.frame ?? fullFrame(atlases[0]!),
+        tint: opts?.tint ?? [1, 1, 1, 1],
+        renderOrder: opts?.renderOrder ?? 0,
+        minScreenPx: opts?.minScreenPx ?? 0,
+        maxScreenPx: opts?.maxScreenPx ?? 0,
+      }
+      let atlas = frameAtlas("addSprite", style)
+      if (opts?.parent && opts.parent.layer !== layer) throw new Error("addSprite: parent group belongs to another layer")
       let slot = freeSlots.pop() ?? highWater++
       if (slot >= gpuCapacity) grow(gpuCapacity * 2)
       let sprite: SpriteState = {
@@ -1038,7 +1236,6 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
       let node = spatial.createNode(TRANSFORM, sprite._visible)
       sprite.node = node
       if (opts?.parent) {
-        if (opts.parent.layer !== layer) throw new Error("addSprite: parent group belongs to another layer")
         spatial.setParent(node, opts.parent.node)
         opts.parent._children.add(sprite)
       } else {
@@ -1047,13 +1244,25 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
       spatial.setBounds(node, COLUMN_BOUNDS)
       spatial.bindPoseRecord(node, pose, slot)
       byNode.set(node, sprite)
-      // renderOrder defaults to 0 explicitly: a recycled slot holds the
-      // previous occupant's key otherwise.
-      writeStyle(sprite, { frame: FULL_FRAME, tint: [1, 1, 1, 1], renderOrder: 0, ...opts })
+      writeStyle(sprite, style, atlas)
+      // No outline until a text run sets one: a recycled slot would
+      // otherwise leak the previous occupant's.
+      styleData.fill(0, slot * STYLE_FLOATS + STYLE_OUTLINE_FIELD, slot * STYLE_FLOATS + STYLE_OUTLINE_FIELD + 4)
       layer._schedule()
       return sprite
     },
+    _outline(sprite, r, g, b, width) {
+      let at = sprite._slot * STYLE_FLOATS + STYLE_OUTLINE_FIELD
+      styleData[at] = r
+      styleData[at + 1] = g
+      styleData[at + 2] = b
+      styleData[at + 3] = width
+      styleDirty = true
+      layer._schedule()
+    },
     _write(sprite, opts) {
+      checkClamp("setSprite", sprite, opts)
+      let atlas = frameAtlas("setSprite", opts)
       let moved = false
       if (opts.x !== undefined && opts.x !== sprite._x) (sprite._x = opts.x), (moved = true)
       if (opts.y !== undefined && opts.y !== sprite._y) (sprite._y = opts.y), (moved = true)
@@ -1071,9 +1280,12 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
         opts.tint !== undefined ||
         opts.flipX !== undefined ||
         opts.flipY !== undefined ||
-        opts.renderOrder !== undefined
+        opts.renderOrder !== undefined ||
+        opts.minScreenPx !== undefined ||
+        opts.maxScreenPx !== undefined ||
+        (moved && clamped.has(sprite))
       ) {
-        writeStyle(sprite, opts)
+        writeStyle(sprite, opts, atlas)
       }
       if (moved || styleDirty) layer._schedule()
     },
@@ -1084,17 +1296,20 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
         y: sprite._y,
         w: sprite._w,
         h: sprite._h,
-        frame: readFrame(styleData, at, sprite),
+        frame: readFrame(styleData, at, sprite, atlases[styleData[at + STYLE_ATLAS_FIELD]!]!.texture),
         flipX: sprite._flipX,
         flipY: sprite._flipY,
         rotation: sprite._rot,
         tint: [styleData[at + 4]!, styleData[at + 5]!, styleData[at + 6]!, styleData[at + 7]!],
+        minScreenPx: styleData[at + STYLE_MIN_PX_FIELD]!,
+        maxScreenPx: styleData[at + STYLE_MAX_PX_FIELD]!,
         renderOrder: styleData[at + STYLE_KEY_FIELD]!,
         visible: sprite._visible,
       }
     },
     _destroy(sprite) {
       sprite.layer = null
+      dropClamp(sprite)
       if (sprite._parent) {
         sprite._parent._children.delete(sprite)
         sprite._parent = null
@@ -1152,17 +1367,30 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
  * notices; a scene that needs depth order sorts by world y with the
  * layer's `orderBy: "y"` (core-produced, zero JS per frame). Past the
  * layer's reservation both instance buffers double (pose sinks move in one
- * core retarget); reserve with `capacity` to avoid the copies.
+ * core retarget); reserve with `capacity` to avoid the copies. An option
+ * left out or passed as undefined takes its default (zero pose and size,
+ * the first atlas whole, an opaque white tint).
  */
 export function addSprite(layer: SpriteLayer | RecordLayer, opts?: AddSpriteOptions): Sprite {
+  if (opts) checkSpriteOptions("addSprite", opts)
   return layer._add(opts)
 }
 
 /** The one write path: absent keys keep their values (the params rule). */
 export function setSprite(sprite: Sprite, opts: SpriteOptions): void {
+  checkSpriteOptions("setSprite", opts)
   sprite.layer?._write(sprite, opts)
 }
 
+/** The validated sprite fields (throws - the dev validation policy),
+ * checked before any state changes: a NaN tint channel or clamp bound
+ * would otherwise blank the sprite with no error. The clamp pair is also
+ * checked against the stored bounds by the layer's write. */
+function checkSpriteOptions(verb: string, opts: SpriteOptions): void {
+  if (opts.tint !== undefined) checkTint(verb, opts.tint)
+  if (opts.minScreenPx !== undefined || opts.maxScreenPx !== undefined) checkScreenSize(verb, opts.minScreenPx ?? 0, opts.maxScreenPx ?? 0)
+}
+
 /** Read a sprite's current fields (a fresh object; mutating it does nothing). */
 export function getSprite(sprite: Sprite): Required<SpriteOptions> | null {
   return sprite.layer ? sprite.layer._read(sprite) : null

package/src/pack.ts

@@ -0,0 +1,70 @@
+// Rect packing, pure: the shelf packer (next-fit decreasing height) that
+// places sizes on a sheet of a given width - what extrudeRects re-places a
+// hand-packed sheet with, and what a runtime atlas packer allocates from.
+// Simple on purpose: a sprite sheet is hundreds of rects, not millions,
+// and shelves keep every placement's x and y a sum of the sizes placed
+// before it, so sizes that are multiples of g land on multiples of g (the
+// alignment extrusion relies on). No imports, so tests/pack.test.ts runs
+// headless on the flux binary.
+
+export type Size = { width: number; height: number }
+export type Placement = { x: number; y: number }
+/** A packing: the sheet size and one placement per input size, in INPUT
+ * order (the packer sorts internally and maps back). */
+export type Packing = { width: number; height: number; rects: Placement[] }
+
+/**
+ * Pack `sizes` onto a sheet `width` wide: tallest first, filled left to
+ * right in shelves as tall as their first (tallest) rect, a new shelf when
+ * the current one is full. Returns the placements in input order and the
+ * height the shelves reach. Throws on a non-positive-integer size or one
+ * wider than the sheet.
+ */
+export function packRects(sizes: readonly Size[], width: number): Packing {
+  if (!(Number.isInteger(width) && width > 0)) throw new Error(`packRects: width must be a positive integer, got ${width}`)
+  sizes.forEach((s, i) => {
+    if (!(Number.isInteger(s.width) && Number.isInteger(s.height) && s.width > 0 && s.height > 0)) {
+      throw new Error(`packRects: sizes[${i}] must be positive integers, got ${s.width} x ${s.height}`)
+    }
+    if (s.width > width) throw new Error(`packRects: sizes[${i}] is ${s.width} wide, past the ${width} sheet`)
+  })
+  // Tallest first, widest among equals, then input order: a total order,
+  // so the packing is the same whatever the input's order of ties.
+  let order = sizes.map((_, i) => i).sort((a, b) => sizes[b]!.height - sizes[a]!.height || sizes[b]!.width - sizes[a]!.width || a - b)
+  let rects: Placement[] = new Array(sizes.length)
+  let x = 0
+  let y = 0
+  let shelf = 0
+  for (let i of order) {
+    let s = sizes[i]!
+    if (x + s.width > width) {
+      y += shelf
+      x = 0
+      shelf = 0
+    }
+    rects[i] = { x, y }
+    x += s.width
+    if (s.height > shelf) shelf = s.height
+  }
+  return { width, height: y + shelf, rects }
+}
+
+/**
+ * A sheet width for `sizes`: the smallest power of two that fits the
+ * widest size and at least the square root of the total area, so the
+ * packing comes out roughly square - the width TexturePacker-class tools
+ * default to. A power of two is a multiple of every smaller power of two,
+ * which keeps an extruded sheet's edges on mip texel edges.
+ */
+export function packWidth(sizes: readonly Size[]): number {
+  let widest = 0
+  let area = 0
+  for (let s of sizes) {
+    widest = Math.max(widest, s.width)
+    area += s.width * s.height
+  }
+  let side = Math.sqrt(area)
+  let width = 1
+  while (width < widest || width < side) width *= 2
+  return width
+}