@solidrt/2d 0.0.56 → 0.0.57

package/src/components/auto-oversample.ts

@@ -0,0 +1,27 @@
+// The auto oversample apply shared by <SpriteLayer> and <TileLayer>: the
+// measured inputs (window texel budget, device limits) around the pure
+// decision in oversample-math.ts.
+import { displayScale, windowSize } from "@solidrt/core"
+import { limits } from "@solidrt/core/gpu"
+import { pickOversample } from "../oversample-math.ts"
+
+// The window's device pixel count: the texel budget an auto-picked
+// oversample target stays within (see fitOversample).
+function windowTexels(): number {
+  let win = windowSize()
+  let scale = displayScale()
+  return win.width * scale * (win.height * scale)
+}
+
+// The auto-pick apply: the decision itself (cap, shrink hysteresis,
+// validation) is pure and lives in oversample-math.ts.
+export function applyOversample(
+  layer: { readonly oversample: number; setOversample(n: number): void },
+  scale: number,
+  targetW: number,
+  targetH: number,
+  max: number | undefined,
+): void {
+  let n = pickOversample(layer.oversample, scale, targetW, targetH, windowTexels(), limits.maxTextureSize, max)
+  if (n !== null) layer.setOversample(n)
+}

package/src/components/camera2d.tsx

@@ -0,0 +1,82 @@
+import { createEffect, merge, onFrame, untrack } from "@solidrt/core"
+import type { InputMap, VoidComponent } from "@solidrt/core"
+import { createCamera2d } from "../camera2d.ts"
+import type { Camera2d as Camera2dHandle, Camera2dAxes, Camera2dOptions } from "../camera2d.ts"
+import { useSpriteLayer } from "./context.ts"
+
+export type Camera2dProps = Omit<Camera2dOptions, "viewport"> & {
+  /** Viewport in layer pixels; defaults to the driven view's own size
+   * (live: a fill layer's box, a setSize, a `<View2d>` resize). */
+  viewport?: () => { width: number; height: number }
+  /** The input map driving the control (InputMap.drive): its `pan`,
+   * `zoom` and `roll` actions, or the ones `actions` names. Live: a new
+   * map reconnects. Without one the control moves only through `ref`. */
+  input?: InputMap<any>
+  /** Action names per axis when the map's differ (null skips an axis). */
+  actions?: Partial<Record<keyof Camera2dAxes, string | null>>
+  ref?: (camera: Camera2dHandle) => void
+}
+
+// Cap on the camera loop's per-frame dt in seconds, so the first tick
+// after a suspended stretch (a resumed app, a reload) cannot leap a glide.
+const MAX_CAMERA_DT = 0.1
+
+/**
+ * createCamera2d as a SpriteLayer child: drives the nearest view's camera
+ * - the `<SpriteLayer>`'s own, or inside a `<View2d>` that view
+ * (useSpriteLayer's `viewport`) - and takes its input from the map in
+ * `input`, nothing else (ARCHITECTURE.md: no device wiring in a
+ * component; the app binds the view's pointer feed, a pad or anything
+ * else to the map). Under a `<SpriteLayer output={false}>` there is no
+ * view to drive: put the `<Camera2d>` inside one of its `<View2d>`
+ * children. The pose props (x, y, zoom, rotation) are initial values:
+ * change the pose at runtime through `ref`'s set/glideTo/fit/follow and
+ * the verbs. Every other prop is live, forwarded to the control as a
+ * getter and read where it applies, so a world, a zoom range, a pivot,
+ * a dead zone or a rate follows its prop, and a bounds or pivot change
+ * re-clamps and pushes the pose at once - the `<OrbitCamera>` rule.
+ * `viewport` defaults to the view's own size. Frames run only while the
+ * camera moves (`active()`), so a resting camera leaves the app
+ * demand-driven idle.
+ */
+export let Camera2d: VoidComponent<Camera2dProps> = props => {
+  let target = useSpriteLayer().viewport
+  // Through merge, not a spread: a props object hands out getters, and
+  // merge keeps them, so the control reads each option live where it
+  // applies.
+  let options: Camera2dOptions = merge(props, {
+    get viewport() {
+      return props.viewport ?? (() => ({ width: target.width, height: target.height }))
+    },
+  })
+  let cam = untrack(() => createCamera2d(target, options))
+  createEffect(
+    () => props.input,
+    input => (input ? input.drive(cam.axes, untrack(() => props.actions)) : undefined),
+  )
+  createEffect(
+    () => cam.active(),
+    on => {
+      if (!on) return
+      let last: number | null = null
+      return onFrame(tick => {
+        let now = tick / 1000
+        let dt = last === null ? 0 : Math.min(now - last, MAX_CAMERA_DT)
+        last = now
+        cam.update(dt)
+      })
+    },
+  )
+  // A bounds or pivot prop change re-clamps and pushes the pose at once
+  // (set({}) applies the clamps). Deferred: the creation already clamped
+  // and pushed the initial pose. Untracked: the control reads the options
+  // through the getters while it applies them, and the apply wants the
+  // values of that moment (the compute above is what tracks them).
+  createEffect(
+    () => [options.world, options.minZoom, options.maxZoom, options.pivot],
+    () => untrack(() => cam.set({})),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(cam)
+  return null
+}

package/src/components/context.ts

@@ -0,0 +1,48 @@
+import { createContext, useContext } from "@solidrt/core"
+import type { PointerFeed } from "@solidrt/core"
+import type { SpriteGroup, SpriteLayer as LayerHandle } from "../layer.ts"
+import type { ViewHandle } from "../views.ts"
+
+export let LayerContext = createContext<LayerHandle>()
+export let GroupContext = createContext<SpriteGroup | null>(null)
+
+// The nearest view: the <SpriteLayer>'s own, or the enclosing <View2d>'s;
+// null under a leafless layer (output={false}) until a <View2d>
+// provides one. Null-default on purpose, like GroupContext.
+export let ViewportContext = createContext<ViewHandle | null>(null)
+// The nearest view's pointer feed (its owner's `pointer` prop), null when
+// none was handed in.
+export let PointerContext = createContext<PointerFeed | null>(null)
+
+type LayerCtx = { layer: LayerHandle; parent: SpriteGroup | null; readonly viewport: ViewHandle; pointer: PointerFeed | null }
+
+/**
+ * The enclosing layer, parent group, view and pointer feed - the
+ * imperative escape hatch inside a component subtree (throws outside a
+ * `<SpriteLayer>`), the same shape as @solidrt/3d's useScene. `parent` is
+ * the enclosing `<Group>`'s handle (null at the layer root); pass it on
+ * to addSprite/addGroup so imperative sprites mount where the JSX sits.
+ * `viewport` is the nearest view: the `<SpriteLayer>`'s own, or inside a
+ * `<View2d>` that view - what a `<Camera2d>` drives, and where a custom
+ * `output` leaf takes its `handlers`. Reading it under a
+ * `<SpriteLayer output={false}>` throws: such a layer shows only through
+ * its `<View2d>` children, so controls and leaves go inside one.
+ * `pointer` is that view's feed (the owner's `pointer` prop), or null.
+ */
+export function useSpriteLayer(): LayerCtx {
+  let layer = useContext(LayerContext)
+  let parent = useContext(GroupContext)
+  let viewport = useContext(ViewportContext)
+  let pointer = useContext(PointerContext)
+  return {
+    layer,
+    parent,
+    pointer,
+    get viewport() {
+      if (viewport === null) {
+        throw new Error("useSpriteLayer: no view here - a <SpriteLayer output={false}> shows only through its <View2d> children; put camera controls and leaves inside one")
+      }
+      return viewport
+    },
+  }
+}

package/src/components/group.tsx

@@ -0,0 +1,68 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { ParentComponent } from "@solidrt/core"
+import { addGroup, removeGroup, setGroup, setGroupTransition } from "../layer.ts"
+import type { SpriteGroup, SpritePointerEvent, SpriteTapEvent, SpriteWheelEvent, TransitionEndEvent } from "../layer.ts"
+import type { NodeTransition } from "flux:spatial"
+import { GroupContext, LayerContext } from "./context.ts"
+
+export type GroupProps = {
+  /** Position in the parent frame (layer pixels at the root). */
+  x?: number
+  y?: number
+  /** Rotation, radians, clockwise. */
+  rotation?: number
+  /** Uniform scale on the whole subtree (child sprites scale with it). */
+  scale?: number
+  /** Show or hide the whole subtree (default true); see
+   * GroupOptions.visible. */
+  visible?: boolean
+  /** Bubbled from a hit child sprite (see SpritePointerProps); a group
+   * never receives enter/leave. */
+  onPointerDown?: (event: SpritePointerEvent) => void
+  onPointerMove?: (event: SpritePointerEvent) => void
+  onPointerUp?: (event: SpritePointerEvent) => void
+  onWheel?: (event: SpriteWheelEvent) => void
+  onTap?: (event: SpriteTapEvent) => void
+  /** How pose-prop changes animate (see setGroupTransition); the mount
+   * pose always snaps. */
+  transition?: NodeTransition | string | null
+  /** A declared transition settled on one component. */
+  onTransitionEnd?: (event: TransitionEndEvent) => void
+  ref?: (group: SpriteGroup) => void
+}
+
+/**
+ * A transform group: `<Sprite>` (and nested `<Group>`) children mount under
+ * its spatial arena node, so their pose props read in the group's frame and
+ * moving the group moves the subtree in one native recompute - a ship with
+ * turrets is one `<Group>` with the hull and turret sprites inside. Renders
+ * nothing itself.
+ */
+export let Group: ParentComponent<GroupProps> = props => {
+  let layer = useContext(LayerContext)
+  let parent = useContext(GroupContext)
+  let group = untrack(() => addGroup(layer, { parent }))
+  createEffect(
+    () => [props.x, props.y, props.rotation, props.scale, props.visible] as const,
+    ([x, y, rotation, scale, visible]) => setGroup(group, { x, y, rotation, scale, visible: visible !== false }),
+  )
+  // After the pose effect, so the mount pose snaps before writes animate.
+  createEffect(
+    () => props.transition,
+    transition => setGroupTransition(group, transition ?? null),
+  )
+  createEffect(
+    () => [props.onPointerDown, props.onPointerMove, props.onPointerUp, props.onWheel, props.onTap, props.onTransitionEnd] as const,
+    ([down, move, up, wheel, tap, end]) => {
+      group.onPointerDown = down
+      group.onPointerMove = move
+      group.onPointerUp = up
+      group.onWheel = wheel
+      group.onTap = tap
+      group.onTransitionEnd = end
+    },
+  )
+  untrack(() => props.ref)?.(group)
+  onCleanup(() => removeGroup(group))
+  return <GroupContext value={group}>{props.children}</GroupContext>
+}

package/src/components/index.ts

@@ -0,0 +1,28 @@
+// The Solid face: PascalCase components over context, syncing the retained
+// layer (layer.ts) - no new intrinsic elements, no renderer changes. Props
+// follow the Solid 2.0 model (reactive values, no destructuring); effects
+// write into the retained records and the runtime's dirty flush renders.
+// Anything moving at frame rate can bypass the declarative layer: grab the
+// sprite with `ref` and call setSprite from onFrame - signals carry
+// structure and slow state, per-frame motion goes straight to the layer.
+// The same split, with the same reasoning, as @solidrt/3d's components.
+//
+// One file per component, with the shared pieces beside them: context.ts
+// (the layer, group and viewport contexts and useSpriteLayer) and
+// auto-oversample.ts (the measured auto-pick the leaves apply). This index is the package's
+// face: index.ts at the root re-exports it, nothing outside imports the
+// files directly.
+
+export { useSpriteLayer } from "./context.ts"
+export { SpriteLayer } from "./sprite-layer.tsx"
+export type { LayerPointerProps, SpriteLayerProps } from "./sprite-layer.tsx"
+export { Group } from "./group.tsx"
+export type { GroupProps } from "./group.tsx"
+export { Sprite } from "./sprite.tsx"
+export type { SpritePointerProps, SpriteProps } from "./sprite.tsx"
+export { Camera2d } from "./camera2d.tsx"
+export type { Camera2dProps } from "./camera2d.tsx"
+export { View2d } from "./view2d.tsx"
+export type { View2dProps } from "./view2d.tsx"
+export { TileLayer } from "./tile-layer.tsx"
+export type { TileCamera, TileLayerProps } from "./tile-layer.tsx"

package/src/components/sprite-layer.tsx

@@ -0,0 +1,312 @@
+import { createEffect, displayScale, getBoundingBoxViewport, getLayoutBox, onCleanup, onLayout, untrack } from "@solidrt/core"
+import type { Element, ParentComponent, PointerFeed, TextureId } from "@solidrt/core"
+import { createSpriteLayer } from "../layer.ts"
+import { feedPointer } from "../views.ts"
+import type { LayerPointerEvent, LayerTapEvent, LayerWheelEvent, SpriteLayer as LayerHandle } from "../layer.ts"
+import type { CameraUpdate } from "../camera.ts"
+import type { ViewHandle } from "../views.ts"
+import { LayerContext, PointerContext, ViewportContext } from "./context.ts"
+import { applyOversample } from "./auto-oversample.ts"
+
+/**
+ * A view's own pointer events, the root of the walk: every event arrives
+ * after the hit sprite and its Groups (`event.sprite` set) or as the only
+ * stop over empty space (`event.sprite` null), unless a handler stopped
+ * it. Deselect on a miss, start a marquee, drive a camera - the
+ * `<Camera2d>` child listens at the same root.
+ */
+export type LayerPointerProps = {
+  onPointerDown?: (event: LayerPointerEvent) => void
+  onPointerMove?: (event: LayerPointerEvent) => void
+  onPointerUp?: (event: LayerPointerEvent) => void
+  onWheel?: (event: LayerWheelEvent) => void
+  onTap?: (event: LayerTapEvent) => void
+}
+
+export type SpriteLayerProps = LayerPointerProps & {
+  /**
+   * View pixels of the layer's own view - give both, or neither. Omitted,
+   * the view FILLS: the built-in leaf is laid out at 100% of its parent's
+   * box (give it a sized parent, as on the web) and the view sizes to that
+   * box, so view pixels are the leaf's own coordinates and sprites place
+   * in element units - the auto oversample still supplies display density
+   * on top. Fill or fixed is decided at mount, and matches @solidrt/3d's
+   * `<Scene>` one dimension down. A function `output` needs explicit
+   * sizes (the view cannot follow a leaf it does not own); the leaf's own
+   * width/height are then layout, so render size and display size
+   * separate.
+   */
+  width?: number
+  height?: number
+  /** The atlas texture every sprite samples (create with createAtlas). */
+  atlas: TextureId
+  /** Initial record reservation (grows on demand); default 1024. */
+  capacity?: number
+  /** The own view's clear color. */
+  clearColor?: [number, number, number, number]
+  /** Pan/zoom/rotate the own view over the world (in-shader); a
+   * shared-params write, never per-sprite. A `<Camera2d>` child writes
+   * the same state - use one form, not both. */
+  camera?: CameraUpdate
+  /**
+   * Layer tint, [r, g, b, a] in 0..1, multiplied over every sprite's own
+   * tint in every view (day/night, a dimmed parallax plane, a fade-in).
+   * One shared uniform write per view, cheap to animate - unlike
+   * TileLayer's, which re-bakes.
+   */
+  tint?: [number, number, number, number]
+  /**
+   * Target texels per view pixel. Absent, the component picks it every
+   * layout from the built-in leaf's on-screen size (display scale, any
+   * designSize fit, layout scaling), so the view resamples properly at any
+   * scale; with a function `output` there is no built-in leaf, so set it
+   * yourself.
+   */
+  oversample?: number
+  /**
+   * Cap on the auto-picked oversample (integer >= 1): the view stays
+   * adaptive up to it, never above - the lever that bounds target memory on
+   * high-scale displays without giving up adaptivity. Ignored when
+   * `oversample` is set (explicit already opts out of the pick).
+   */
+  maxOversample?: number
+  /**
+   * Draw sprites in key order instead of slot order, produced by core at
+   * every publish: `"y"` orders by world y (back-to-front for a
+   * perspective scene, zero JS per frame even under native transitions),
+   * `"renderOrder"` by the per-sprite `renderOrder` field (explicit layering:
+   * raise-on-drag, click-to-front). Creation-fixed (see
+   * SpriteLayerOptions.orderBy).
+   */
+  orderBy?: "y" | "renderOrder"
+  label?: string
+  /** The layer: sprites, tint, pick, createView. */
+  ref?: (layer: LayerHandle) => void
+  /** The layer's own view (texture, camera, handlers) for imperative use
+   * outside the tree; inside, `useSpriteLayer().viewport` is the same.
+   * Not called with `output={false}` - there is no own view. */
+  viewRef?: (view: ViewHandle) => void
+  /**
+   * The own view's leaf. Absent: a built-in `<texture>` leaf carrying the
+   * view's handlers. A function: compose the leaf yourself - called once
+   * (untracked) with the view's texture id, its return renders in place
+   * of the built-in leaf; sprite pointer events then need the view's
+   * handlers on your leaf: `<texture src={texture}
+   * {...useSpriteLayer().viewport.handlers} />`. `false`: NO view of its
+   * own - the layer shows only through its `<View2d>` children, each a
+   * full view with its own camera (split-screen: two side by side, a
+   * game with its minimap and nothing else). The view props (width,
+   * height, camera, clearColor, oversample, maxOversample, events,
+   * viewRef, the pointer props) then have nothing to apply to and throw.
+   */
+  output?: ((texture: TextureId) => Element) | false
+  /**
+   * Pointer events (default on): the built-in leaf carries the view's
+   * handlers, so sprites, groups, the view's own handlers and a
+   * `<Camera2d>` child receive input. `false` detaches them - the leaf
+   * then costs no pointer routing at all.
+   */
+  events?: boolean
+  /**
+   * The pointer feed of the layer's own view (createPointerFeed), fed
+   * from the view's root - the events the sprites let through: a sprite
+   * that claims its press keeps a camera bound to the feed out of that
+   * drag - so an input map over it drives the `<Camera2d>` child; inside,
+   * `useSpriteLayer().pointer` is this feed. Fixed at creation.
+   */
+  pointer?: PointerFeed
+}
+
+// Creation size of a fill-mode view: the first onLayout replaces it
+// before the first paint, so it only has to be a valid target size.
+const FILL_INITIAL_SIZE = 1
+
+// The props that configure the layer's own view - meaningless, hence
+// rejected, on a layer without one (output={false}).
+const VIEW_PROPS = [
+  "width",
+  "height",
+  "camera",
+  "clearColor",
+  "oversample",
+  "maxOversample",
+  "events",
+  "pointer",
+  "viewRef",
+  "onPointerDown",
+  "onPointerMove",
+  "onPointerUp",
+  "onWheel",
+  "onTap",
+] as const
+
+/**
+ * Owns a sprite layer and, unless `output={false}`, its own view,
+ * composited as an ordinary `<texture>` leaf so the output takes layout,
+ * transforms, blendMode, and pointer events like any element - or hand
+ * `output` the texture id and compose it yourself. A layout component:
+ * it cannot sit inside a d-* subtree; `output` with a `<d-texture>` is
+ * the detached form. Children (`<Sprite>`) render nothing themselves -
+ * they populate the retained layer through context; `<View2d>` children
+ * are further views of the same sprites.
+ */
+export let SpriteLayer: ParentComponent<SpriteLayerProps> = props => {
+  let layer = untrack(() =>
+    createSpriteLayer(props.atlas, {
+      capacity: props.capacity,
+      tint: props.tint,
+      orderBy: props.orderBy,
+      label: props.label,
+    }),
+  )
+  createEffect(
+    () => props.tint,
+    tint => {
+      if (tint !== undefined) layer.setTint(tint)
+    },
+  )
+  untrack(() => props.ref)?.(layer)
+  let output = untrack(() => props.output)
+  if (output === false) {
+    untrack(() => {
+      for (let name of VIEW_PROPS) {
+        if (props[name] !== undefined) throw new Error(`SpriteLayer: output={false} has no view of its own - ${name} belongs on a <View2d> child`)
+      }
+    })
+    return (
+      <LayerContext value={layer}>
+        <ViewportContext value={null}>{props.children}</ViewportContext>
+      </LayerContext>
+    )
+  }
+  // Fill vs fixed view is decided at mount, like `output`: both width
+  // and height (fixed view pixels) or neither (fill).
+  let fill = untrack(() => {
+    if ((props.width === undefined) !== (props.height === undefined)) {
+      throw new Error("SpriteLayer: width and height come together - give both (fixed view) or neither (fill)")
+    }
+    if (props.width === undefined && output) {
+      throw new Error("SpriteLayer: fill needs the built-in leaf - with output, give width and height")
+    }
+    return props.width === undefined
+  })
+  // The layer's own view: the initial props seed it, the effects follow
+  // changes only (`defer`).
+  let view = untrack(() =>
+    layer.createView({
+      width: props.width ?? FILL_INITIAL_SIZE,
+      height: props.height ?? FILL_INITIAL_SIZE,
+      camera: props.camera,
+      oversample: props.oversample,
+      clearColor: props.clearColor,
+      label: props.label,
+    }),
+  )
+  createEffect(
+    () => [props.width, props.height] as const,
+    ([w, h]) => {
+      if ((w === undefined) !== (h === undefined) || (w === undefined) !== fill) {
+        throw new Error("SpriteLayer: fill/fixed is mount-fixed - width/height cannot appear or disappear")
+      }
+      if (!fill) view.setSize(w!, h!)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.camera,
+    camera => {
+      if (camera) view.setCamera(camera)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.oversample,
+    n => {
+      if (n !== undefined) view.setOversample(n)
+    },
+    { defer: true },
+  )
+  untrack(() => props.viewRef)?.(view)
+  let pointer = untrack(() => props.pointer) ?? null
+  if (pointer) onCleanup(feedPointer(view, pointer))
+  // The view's own handlers at the root of the walk; the props are read
+  // per event, so a handler prop may change without re-registering.
+  onCleanup(
+    view.listen({
+      onPointerDown: e => props.onPointerDown?.(e),
+      onPointerMove: e => props.onPointerMove?.(e),
+      onPointerUp: e => props.onPointerUp?.(e),
+      onWheel: e => props.onWheel?.(e),
+      onTap: e => props.onTap?.(e),
+    }),
+  )
+  let events = untrack(() => props.events) !== false
+  let leaf: { id: number } | undefined
+  // The view's pixel size: the props in fixed mode, the built-in leaf's
+  // laid-out box in fill mode (getLayoutBox, the untransformed read, so a
+  // designSize fit or ancestor transform never enters the world space -
+  // display density rides on the oversample pick below). Null before the
+  // first layout.
+  let viewSize = (): { width: number; height: number } | null => {
+    if (!fill) return { width: props.width!, height: props.height! }
+    let box = leaf && getLayoutBox(leaf)
+    if (!box || box.width <= 0 || box.height <= 0) return null
+    return { width: Math.max(1, Math.round(box.width)), height: Math.max(1, Math.round(box.height)) }
+  }
+  // Fill: the view follows the leaf's box. Registered before the pick, so
+  // one onLayout applies size then oversample in order; setSize no-ops
+  // when nothing changed.
+  if (fill) {
+    onLayout(() => {
+      let size = viewSize()
+      if (size) view.setSize(size.width, size.height)
+    })
+  }
+  // Auto oversample: the built-in leaf's window box, in device pixels, per
+  // view pixel. Picked after every layout, and again when the display scale
+  // changes: the first layout runs before the resize event that reports the
+  // scale, and a scale change alone lays nothing out. pick runs as an
+  // onLayout handler and as an effect apply, both untracked scopes, so its
+  // prop reads are wrapped in an explicit untrack.
+  let pick = () =>
+    untrack(() => {
+      if (!leaf || props.oversample !== undefined) return
+      let box = getBoundingBoxViewport(leaf)
+      let size = viewSize()
+      if (!box || !size) return
+      let scale = displayScale() * Math.max(box.width / size.width, box.height / size.height)
+      applyOversample(view, scale, size.width, size.height, props.maxOversample)
+    })
+  onLayout(pick)
+  createEffect(() => [displayScale(), props.maxOversample], pick)
+  // Sprite events on the built-in leaf: at view size the plain handlers,
+  // in fill mode scaled from the laid-out box (the box can be fractional,
+  // the view size never is).
+  let viewHandlers = fill
+    ? view.handlersFor(() => (leaf && getLayoutBox(leaf)) || { width: 0, height: 0 })
+    : view.handlers
+  return (
+    <LayerContext value={layer}>
+      <ViewportContext value={view}>
+        <PointerContext value={pointer}>
+          {output ? (
+            untrack(() => output(view.texture))
+          ) : (
+            <texture
+              ref={(n: { id: number }) => (leaf = n)}
+              src={view.texture}
+              width={fill ? "100%" : props.width}
+              height={fill ? "100%" : props.height}
+              onPointerDown={events ? viewHandlers.onPointerDown : undefined}
+              onPointerMove={events ? viewHandlers.onPointerMove : undefined}
+              onPointerUp={events ? viewHandlers.onPointerUp : undefined}
+              onPointerLeave={events ? viewHandlers.onPointerLeave : undefined}
+              onWheel={events ? viewHandlers.onWheel : undefined}
+            />
+          )}
+          {props.children}
+        </PointerContext>
+      </ViewportContext>
+    </LayerContext>
+  )
+}

package/src/components/sprite.tsx

@@ -0,0 +1,72 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { addSprite, removeSprite, setSprite, setSpriteTransition } from "../layer.ts"
+import type { Sprite as SpriteHandle, SpriteOptions, SpritePointerEvent, SpriteTapEvent, SpriteWheelEvent, TransitionEndEvent } from "../layer.ts"
+import type { NodeTransition } from "flux:spatial"
+import { GroupContext, LayerContext } from "./context.ts"
+
+/**
+ * Sprite pointer events, the element vocabulary one tree deeper: the
+ * topmost hit sprite receives the event, down/move/up/wheel/tap bubble to
+ * enclosing Groups and end at the `<SpriteLayer>` (stopPropagation stops
+ * the walk; stopping a down claims the whole press), enter/leave pair on
+ * the sprite alone. Events flow while the element showing the layer
+ * carries layer.handlers - the built-in `<SpriteLayer>` leaf does (opt
+ * out with events={false}); an `output` leaf spreads them itself.
+ */
+export type SpritePointerProps = {
+  onPointerDown?: (event: SpritePointerEvent) => void
+  onPointerMove?: (event: SpritePointerEvent) => void
+  onPointerUp?: (event: SpritePointerEvent) => void
+  /** Sprites only: a Group never receives enter/leave. */
+  onPointerEnter?: (event: SpritePointerEvent) => void
+  onPointerLeave?: (event: SpritePointerEvent) => void
+  onWheel?: (event: SpriteWheelEvent) => void
+  /** A press released on the sprite without dragging; `tapCount` counts
+   * repeats (2 = double tap). */
+  onTap?: (event: SpriteTapEvent) => void
+}
+
+export type SpriteProps = SpriteOptions &
+  SpritePointerProps & {
+    /** How pose-prop changes animate (see setSpriteTransition); the mount
+     * pose always snaps. */
+    transition?: NodeTransition | string | null
+    /** A declared transition settled on one component. */
+    onTransitionEnd?: (event: TransitionEndEvent) => void
+    ref?: (sprite: SpriteHandle) => void
+  }
+
+/** One sprite: a frame drawn at a position (in the enclosing `<Group>`'s
+ * frame when there is one). */
+export let Sprite: VoidComponent<SpriteProps> = props => {
+  let layer = useContext(LayerContext)
+  let parent = useContext(GroupContext)
+  let sprite = untrack(() => addSprite(layer, { parent }))
+  createEffect(
+    () => [props.x, props.y, props.w, props.h, props.frame, props.flipX, props.flipY, props.rotation, props.tint, props.renderOrder, props.visible] as const,
+    ([x, y, w, h, frame, flipX, flipY, rotation, tint, renderOrder, visible]) =>
+      setSprite(sprite, { x, y, w, h, frame, flipX, flipY, rotation, tint, renderOrder, visible: visible !== false }),
+  )
+  // After the pose effect, so the mount pose snaps before writes animate.
+  createEffect(
+    () => props.transition,
+    transition => setSpriteTransition(sprite, transition ?? null),
+  )
+  createEffect(
+    () => [props.onPointerDown, props.onPointerMove, props.onPointerUp, props.onPointerEnter, props.onPointerLeave, props.onWheel, props.onTap, props.onTransitionEnd] as const,
+    ([down, move, up, enter, leave, wheel, tap, end]) => {
+      sprite.onPointerDown = down
+      sprite.onPointerMove = move
+      sprite.onPointerUp = up
+      sprite.onPointerEnter = enter
+      sprite.onPointerLeave = leave
+      sprite.onWheel = wheel
+      sprite.onTap = tap
+      sprite.onTransitionEnd = end
+    },
+  )
+  untrack(() => props.ref)?.(sprite)
+  onCleanup(() => removeSprite(sprite))
+  return null
+}